From 44825f25dc31ac97013bdc9e69855c1c4c7c4f74 Mon Sep 17 00:00:00 2001 From: Siddharth Chandrasekaran Date: Wed, 13 Mar 2024 22:54:51 +0100 Subject: [PATCH] doc: Fixup doc in multiple places Signed-off-by: Siddharth Chandrasekaran --- doc/api/command-structure.rst | 116 ++++++++++-------------------- doc/api/control-panel.rst | 25 +++++-- doc/api/event-structure.rst | 47 ++++++++++++ doc/api/index.rst | 1 + doc/api/peripheral-device.rst | 15 ++-- doc/index.rst | 1 + doc/libosdp/build-and-install.rst | 24 +++++-- doc/libosdp/cross-compiling.rst | 22 +++++- 8 files changed, 155 insertions(+), 96 deletions(-) create mode 100644 doc/api/event-structure.rst diff --git a/doc/api/command-structure.rst b/doc/api/command-structure.rst index 333d7e0c..5e3ee78f 100644 --- a/doc/api/command-structure.rst +++ b/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 diff --git a/doc/api/control-panel.rst b/doc/api/control-panel.rst index d6d03ec2..bea8f84e 100644 --- a/doc/api/control-panel.rst +++ b/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. diff --git a/doc/api/event-structure.rst b/doc/api/event-structure.rst new file mode 100644 index 00000000..1d6fedb6 --- /dev/null +++ b/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 diff --git a/doc/api/index.rst b/doc/api/index.rst index 270f3db4..fd3f29cc 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -8,4 +8,5 @@ API peripheral-device miscellaneous command-structure + event-structure channel diff --git a/doc/api/peripheral-device.rst b/doc/api/peripheral-device.rst index 43756084..4d04b8a4 100644 --- a/doc/api/peripheral-device.rst +++ b/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 \ No newline at end of file diff --git a/doc/index.rst b/doc/index.rst index 9d7122f6..eb0da9d6 100644 --- a/doc/index.rst +++ b/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:: diff --git a/doc/libosdp/build-and-install.rst b/doc/libosdp/build-and-install.rst index 311b895d..15ecabc4 100644 --- a/doc/libosdp/build-and-install.rst +++ b/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. \ No newline at end of file diff --git a/doc/libosdp/cross-compiling.rst b/doc/libosdp/cross-compiling.rst index c6e21596..cfcc5f80 100644 --- a/doc/libosdp/cross-compiling.rst +++ b/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