doc: Fixup doc in multiple places

Signed-off-by: Siddharth Chandrasekaran <[email protected]>

doc/api/command-structure.rst

@@ -1,5 +1,5 @@
-Command structures
-==================
+LibOSDP App Commands
+====================
 
 LibOSDP exposes the following structures thought ``osdp.h``. This document
 attempts to document each of its members. The following structure is used as a
@@ -8,121 +8,77 @@ wrapper for all the commands for convenience.
 .. code:: c
 
     struct osdp_cmd {
-        enum osdp_cmd_e id;
+        enum osdp_cmd_e id; // Command ID. Used to select specific commands in union
         union {
-            struct osdp_cmd_led    led;
+            struct osdp_cmd_led led;
             struct osdp_cmd_buzzer buzzer;
-            struct osdp_cmd_text   text;
+            struct osdp_cmd_text text;
             struct osdp_cmd_output output;
             struct osdp_cmd_comset comset;
             struct osdp_cmd_keyset keyset;
-            struct osdp_cmd_mfg    mfg;
+            struct osdp_cmd_mfg mfg;
+	    struct osdp_cmd_file_tx file_tx;
+	    struct osdp_status_report status;
         };
     };
 
-.. doxygenenum:: osdp_cmd_e
+Below are the structure of each of the command structures.
 
-.. doxygenstruct:: osdp_cmd
-   :members:
-
-Command LED
+LED command
 -----------
 
-.. code:: c
-
-    struct osdp_cmd_led_params {
-        uint8_t control_code;
-        uint8_t on_count;
-        uint8_t off_count;
-        uint8_t on_color;
-        uint8_t off_color;
-        uint16_t timer_count;
-    };
-
-    struct osdp_cmd_led {
-        uint8_t reader;
-        uint8_t number;
-        struct osdp_cmd_led_params temporary;
-        struct osdp_cmd_led_params permanent;
-    };
-
 .. doxygenstruct:: osdp_cmd_led_params
    :members:
 
 .. doxygenstruct:: osdp_cmd_led
    :members:
 
-Command Output
+Buzzer command
 --------------
 
-.. code:: c
+.. doxygenstruct:: osdp_cmd_buzzer
+   :members:
 
-    struct osdp_cmd_output {
-        uint8_t output_no;
-        uint8_t control_code;
-        uint16_t timer_count;
-    };
+Text command
+------------
 
-.. doxygenstruct:: osdp_cmd_output
+.. doxygenstruct:: osdp_cmd_text
    :members:
 
-Command Buzzer
+Output command
 --------------
 
-.. code:: c
-
-    struct osdp_cmd_buzzer {
-        uint8_t reader;
-        uint8_t control_code;
-        uint8_t on_count;
-        uint8_t off_count;
-        uint8_t rep_count;
-    };
-
-.. doxygenstruct:: osdp_cmd_buzzer
+.. doxygenstruct:: osdp_cmd_output
    :members:
 
-Command Text
-------------
-
-.. code:: c
-
-    struct osdp_cmd_text {
-        uint8_t reader;
-        uint8_t control_code;
-        uint8_t temp_time;
-        uint8_t offset_row;
-        uint8_t offset_col;
-        uint8_t length;
-        uint8_t data[32];
-    };
+Comset command
+--------------
 
-.. doxygenstruct:: osdp_cmd_text
+.. doxygenstruct:: osdp_cmd_comset
    :members:
 
-Command Comset
+Keyset command
 --------------
 
-.. code:: c
+.. doxygenstruct:: osdp_cmd_keyset
+   :members:
 
-    struct osdp_cmd_comset {
-        uint8_t address;
-        uint32_t baud_rate;
-    };
+Manufacture specific command
+----------------------------
 
-.. doxygenstruct:: osdp_cmd_comset
+.. doxygenstruct:: osdp_cmd_mfg
    :members:
 
-Command Keyset
---------------
+File transfer command
+---------------------
 
-.. code:: c
+.. doxygenstruct:: osdp_cmd_file_tx
+   :members:
 
-    struct osdp_cmd_keyset {
-        uint8_t type;
-        uint8_t length;
-        uint8_t data[OSDP_CMD_KEYSET_KEY_MAX_LEN];
-    };
+Status report command
+---------------------
 
-.. doxygenstruct:: osdp_cmd_keyset
+.. doxygenstruct:: osdp_status_report
    :members:
+
+.. doxygenenum:: osdp_status_report_type

doc/api/control-panel.rst

@@ -1,7 +1,14 @@
 Control Panel
 =============
 
-The following functions are used when OSDP is to be used in CP mode.
+The following functions are used when OSDP is to be used in CP mode. The library
+returns a single opaque pointer of type ``osdp_t`` where it maintains all it's
+internal data. All applications consuming this library must pass this context
+pointer all API calls.
+
+For the CP application, it's connected PDs are referenced by the offset number
+(0-indexed). This offset corresponds to the order in which the
+``osdp_pd_info_t`` was populated when passed to ``osdp_cp_setup``.
 
 Device lifecycle management
 ---------------------------
@@ -20,21 +27,29 @@ Device lifecycle management
 Events
 ------
 
-.. doxygenstruct:: osdp_event
+Events are generated by the PD and sent to the CP. The CP app can register a
+callback using ``osdp_cp_set_event_callback`` to get notified of events.
 
 .. doxygentypedef:: cp_event_callback_t
 
 .. doxygenfunction:: osdp_cp_set_event_callback
 
+Refer to the `event structure`_ document for more information on how the
+``event`` structure is framed.
+
+.. _event structure: event-structure.html
+
 Commands
 --------
 
-For the CP application, it's connected PDs are referenced by the offset number.
-This offset corresponds to the order in which the ``osdp_pd_info_t`` was
-populated when passed to ``osdp_cp_setup``.
+Commands are sent from the CP to the PD to perform various actions. The CP app
+has to create a command struct and then call ``osdp_cp_send_command`` to enqueue
+the command to a particular PD.
 
 .. doxygenfunction:: osdp_cp_send_command
 
+.. doxygenfunction:: osdp_cp_flush_commands
+
 Refer to the `command structure`_ document for more information on how to
 populate the ``cmd`` structure for these function.
 

doc/api/event-structure.rst

@@ -0,0 +1,47 @@
+LibOSDP App Events
+==================
+
+LibOSDP exposes the following structures thought ``osdp.h``. This document
+attempts to document each of its members. The following structure is used as a
+wrapper for all the events for convenience.
+
+.. code:: c
+
+    struct osdp_event {
+        enum osdp_event_type type; // Used to select specific event in union
+        union {
+            struct osdp_event_keypress keypress;
+            struct osdp_event_cardread cardread;
+            struct osdp_event_mfgrep mfgrep;
+            struct osdp_status_report status;
+        };
+    };
+
+Below are the structure of each of the event structures.
+
+
+Key press Event
+---------------
+
+.. doxygenstruct:: osdp_event_keypress
+   :members:
+
+Card read Event
+---------------
+
+.. doxygenstruct:: osdp_event_cardread
+   :members:
+
+Manufacture specific reply Event
+--------------------------------
+
+.. doxygenstruct:: osdp_event_mfgrep
+   :members:
+
+Status report request Event
+---------------------------
+
+.. doxygenstruct:: osdp_status_report
+   :members:
+
+.. doxygenenum:: osdp_status_report_type

doc/api/index.rst

@@ -8,4 +8,5 @@ API
    peripheral-device
    miscellaneous
    command-structure
+   event-structure
    channel

doc/api/peripheral-device.rst

@@ -6,7 +6,6 @@ returns a single opaque pointer of type ``osdp_t`` where it maintains all it's
 internal data. All applications consuming this library must pass this context
 pointer all API calls.
 
-
 Device lifecycle management
 ---------------------------
 
@@ -37,17 +36,23 @@ Commands
 
 .. doxygenfunction:: osdp_pd_set_command_callback
 
-Refer to the `command structure`_ document for more information on how to
-populate the ``cmd`` structure for these function.
+Refer to the `command structure`_ document for more information on how the
+``cmd`` structure is framed.
 
 .. _command structure: command-structure.html
 
 Events
 ------
 
-.. doxygenstruct:: osdp_event
-   :members:
+When a PD app has some event (card read, key press, etc.,) to be reported to the
+CP, it creates the corresponding event structure and calls
+``osdp_pd_notify_event`` to deliver it to the CP on the next osdp_POLL command.
 
 .. doxygenfunction:: osdp_pd_notify_event
 
 .. doxygenfunction:: osdp_pd_flush_events
+
+Refer to the `event structure`_ document for more information on how to
+populate the ``event`` structure for these function.
+
+.. _event structure: event-structure.html

doc/index.rst

@@ -126,6 +126,7 @@ of the protocol support only the most common among them. You can see a
    api/peripheral-device
    api/miscellaneous
    api/command-structure
+   api/event-structure
    api/channel
 
 .. toctree::

doc/libosdp/build-and-install.rst

@@ -45,7 +45,7 @@ HTML docs of LibOSDP depends on python3, pip3, doxygen, sphinx, and breathe.
 
 .. code:: sh
 
-    pip3 install -r requirements.txt
+    pip3 install -r doc/requirements.txt
     mkdir build && cd build
     cmake ..
     make html_docs
@@ -77,15 +77,23 @@ the flag ``-DCONFIG_OSDP_BUILD_STATIC=ON`` to cmake.
 Add LibOSDP to your cmake project
 ---------------------------------
 
-If you are familiar with cmake, then adding LibOSDP to your project is
-super simple. First off, add the following to your CMakeLists.txt
+Cmake find_package
+^^^^^^^^^^^^^^^^^^
+
+Build and install LibOSDP to some standard location such ``/usr/local/`` and
+then use cmake's popular find_package() method.
+
+Cmake external project
+^^^^^^^^^^^^^^^^^^^^^^
+
+Start by adding the following to your CMakeLists.txt
 
 .. code:: cmake
 
     include(ExternalProject)
     ExternalProject_Add(ext_libosdp
         GIT_REPOSITORY    https://github.com/cbsiddharth/libosdp.git
-        GIT_TAG           master
+        GIT_TAG           v3.0.2 # update this to the latest version
         SOURCE_DIR        ${CMAKE_BINARY_DIR}/libosdp/src
         BINARY_DIR        ${CMAKE_BINARY_DIR}/libosdp/build
         CONFIGURE_COMMAND cmake ${CMAKE_BINARY_DIR}/libosdp/src
@@ -95,7 +103,7 @@ super simple. First off, add the following to your CMakeLists.txt
     include_directories("${CMAKE_BINARY_DIR}/libosdp/install/usr/local/include")
     link_directories("${CMAKE_BINARY_DIR}/libosdp/install/usr/local/lib")
 
-Next you must add ``ext_libosdp`` as a dependency to your target. That
+Next, you must add ``ext_libosdp`` as a dependency to your target. That's
 it! now you can link your application to osdp library. Following example shows
 how you can do this.
 
@@ -110,3 +118,9 @@ how you can do this.
     add_executable(${OSDP_APP} ${OSDP_APP_SRC})
     add_dependencies(${OSDP_APP} ext_libosdp)
     target_link_libraries(${OSDP_APP} osdp)
+
+Using pkg-config
+^^^^^^^^^^^^^^^^
+
+If you are familiar with pkg-config based dependency resolution methods, LibOSDP
+provides a libosdp.pc file which is installed along with the library.

doc/libosdp/cross-compiling.rst

@@ -1,5 +1,13 @@
 Cross Compiling
----------------
+===============
+
+LibOSDP is written in C and does not depend on any other libraries. You can
+compile it to pretty much any platform (even Windows). Follow the cross
+compilation best practice for your platform. This document gives you some ideas
+on how this can be done but is in no way conclusive.
+
+Using Cmake
+-----------
 
 LibOSDP can be compiled with your cross compiler by passing a toolchain file to
 cmake. This can be done by invoking cmake with the command line argument
@@ -36,3 +44,15 @@ For convenience, the ``toolchain-file.cmake`` file can be placed in a common pat
     mkdir build && cd build
     cmake -DCMAKE_TOOLCHAIN_FILE=/opt/toolchain/armv8l-linux-gnueabihf/toolchain-file.cmake ..
     make
+
+Using make build
+----------------
+
+You could use the ``--cross-compile`` flag in configure.sh and then invoke make
+to build the library.
+
+.. code:: sh
+
+    ./configure.sh --cross-compile arm-none-
+    make
+    make DESTDIR=/opt/arm-none-sysroot/ install