Merge branch 'develop'

.github/workflows/release.yml

@@ -0,0 +1,27 @@
+on:
+  push:
+    # Sequence of patterns matched against refs/tags
+    tags:
+      - 'v*' # Push events to matching v*, i.e. v1.0, v20.15.10
+
+name: Create Release
+
+jobs:
+  build:
+    name: Create Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+      - name: Create Release
+        id: create_release
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # This token is provided by Actions, you do not need to create your own token
+        with:
+          tag_name: ${{ github.ref }}
+          release_name: Release ${{ github.ref }}
+          body: |
+            See the CHANGELOG.md
+          draft: false
+          prerelease: false

CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## Develop
+
+## v1.2.0
+
+- Added support for events on packet ready, read or write operation
+- Add `library.json` for platform.io
+
+## v1.1.0
+
+- Added support for variable length for address fields
+
+## v1.0.1
+
+- Added sphinx documentation to the repository
+- Improved code documentation for doxygen compliancy
+
+## v1.0.0
+
+- First stable release

README.md

@@ -8,6 +8,7 @@
 * Platform independent, no architecture specific code
 * Uses *LwRB* library for data read/write operations
 * Optimized for embedded systems, allows high optimization for data transfer
+* Support for events on packet ready, read or write operation
 * Configurable settings for packet structure and variable data length
 * Allows multiple notes in network with `from` and `to` addresses
 * Separate optional field for *command* data type

docs/conf.py

@@ -26,27 +26,32 @@
 copyright = '2020, Tilen MAJERLE'
 author = 'Tilen MAJERLE'
 
-# The full version, including alpha/beta/rc tags
-version = 'v1.1.0'
-
 # Try to get branch at which this is running
 # and try to determine which version to display in sphinx
+# Version is using git tag if on master or "latest-develop" if on develop branch
+version = ''
 git_branch = ''
+
+# Get current branch
 res = os.popen('git branch').read().strip()
 for line in res.split("\n"):
     if line[0] == '*':
         git_branch = line[1:].strip()
 
 # Decision for display version
-try:
-    if git_branch.index('develop') >= 0:
-        version = "latest-develop"
-except Exception:
-    print("Exception for index check")
-
-# For debugging purpose
+git_branch = git_branch.replace('(HEAD detached at ', '').replace(')', '')
+if git_branch.find('master') >= 0 or git_branch.find('main') >= 0:
+    version = os.popen('git describe --tags --abbrev=0').read().strip()
+    if version == '':
+        version = 'v0.0.0'
+elif git_branch.find('develop') != -1 and not (git_branch.find('develop-') >= 0 or git_branch.find('develop/') >= 0):
+    version = 'latest-develop'
+else:
+    version = 'branch-' + git_branch
+
+# For debugging purpose only
 print("GIT BRANCH: " + git_branch)
-print("VERSION: " + version)
+print("GIT VERSION: " + version)
 
 # -- General configuration ---------------------------------------------------
 

docs/get-started/index.rst

@@ -3,15 +3,21 @@
 Getting started
 ===============
 
+Getting started may be the most challenging part of every new library.
+This guide is describing how to start with the library quickly and effectively
+
 .. _download_library:
 
 Download library
 ^^^^^^^^^^^^^^^^
 
 Library is primarly hosted on `Github <https://github.com/MaJerle/lwpkt>`_.
 
-* Download latest release from `releases area <https://github.com/MaJerle/lwpkt/releases>`_ on Github
-* Clone `develop` branch for latest development
+You can get it with:
+
+* Downloading latest release from `releases area <https://github.com/MaJerle/lwpkt/releases>`_ on Github
+* Cloning ``master`` branch for latest stable version
+* Cloning ``develop`` branch for latest development
 
 Download from releases
 **********************
@@ -24,7 +30,9 @@ Clone from Github
 First-time clone
 """"""""""""""""
 
-* Download and install ``git`` if not already
+This is used when you do not have yet local copy on your machine.
+
+* Make sure ``git`` is installed.
 * Open console and navigate to path in the system to clone repository to. Use command ``cd your_path``
 * Clone repository with one of available ``3`` options
 
@@ -38,50 +46,58 @@ Update cloned to latest version
 """""""""""""""""""""""""""""""
 
 * Open console and navigate to path in the system where your resources repository is. Use command ``cd your_path``
-* Run ``git pull origin master --recurse-submodules`` command to pull latest changes and to fetch latest changes from submodules
+* Run ``git pull origin master --recurse-submodules`` command to pull latest changes and to fetch latest changes from submodules on ``master`` branch
+* Run ``git pull origin develop --recurse-submodules`` command to pull latest changes and to fetch latest changes from submodules on ``develop`` branch
 * Run ``git submodule foreach git pull origin master`` to update & merge all submodules
 
 .. note::
-	This is preferred option to use when you want to evaluate library and run prepared examples.
-	Repository consists of multiple submodules which can be automatically downloaded when cloning and pulling changes from root repository.
+  This is preferred option to use when you want to evaluate library and run prepared examples.
+  Repository consists of multiple submodules which can be automatically downloaded when cloning and pulling changes from root repository.
 
 Add library to project
 ^^^^^^^^^^^^^^^^^^^^^^
 
 At this point it is assumed that you have successfully download library, either cloned it or from releases page.
+Next step is to add the library to the project, by means of source files to compiler inputs and header files in search path
 
-* Copy ``lwpkt`` folder to your project
-* Add ``lwpkt/src/include`` folder to `include path` of your toolchain
-* Add ``libs/lwrb/src/include`` folder to `include path` of your toolchain
-* Add source files from ``lwpkt/src/`` folder to toolchain build
-* Add source files from ``libs/lwrb/src/`` folder to toolchain build
+* Copy ``lwpkt`` folder to your project, it contains library files
+* Add ``lwpkt/src/include`` folder to `include path` of your toolchain. This is where `C/C++` compiler can find the files during compilation process. Usually using ``-I`` flag
+* Add source files from ``lwpkt/src/`` folder to toolchain build. These files are built by `C/C++` compiler
+* Copy ``lwpkt/src/include/lwpkt/lwpkt_opts_template.h`` to project folder and rename it to ``lwpkt_opts.h``
 * Build the project
 
 Configuration file
 ^^^^^^^^^^^^^^^^^^
 
+Configuration file is used to overwrite default settings defined for the essential use case.
 Library comes with template config file, which can be modified according to needs.
-This file shall be named ``lwpkt_opts.h`` and its default template looks like the one below.
+and it should be copied (or simply renamed in-place) and named ``lwpkt_opts.h``
 
 .. note::
     Default configuration template file location: ``lwpkt/src/include/lwpkt/lwpkt_opts_template.h``.
-    File must be renamed to ``lwpkt_opts.h`` first and then copied to the project directory (or simply renamed in-place) where compiler
+    File must be renamed to ``lwpkt_opts.h`` first and then copied to the project directory where compiler
     include paths have access to it by using ``#include "lwpkt_opts.h"``.
 
-.. tip::
-    Check :ref:`api_lwpkt_opt` section for possible configuration settings
+List of configuration options are available in the :ref:`api_lwpkt_opt` section.
+If any option is about to be modified, it should be done in configuration file
 
 .. literalinclude:: ../../lwpkt/src/include/lwpkt/lwpkt_opts_template.h
     :language: c
     :linenos:
-    :caption: Template options file
+    :caption: Template configuration file
+
+.. note::
+    If you prefer to avoid using configuration file, application must define
+    a global symbol ``LWPKT_IGNORE_USER_OPTS``, visible across entire application.
+    This can be achieved with ``-D`` compiler option.
 
 Minimal example code
 ^^^^^^^^^^^^^^^^^^^^
 
-Run below example to test and verify library
+To verify proper library setup, minimal example has been prepared.
+Run it in your main application file to verify its proper execution
 
 .. literalinclude:: ../../examples/example_lwpkt.c
     :language: c
     :linenos:
-    :caption: Simple demo example to test functionality
+    :caption: Absolute minimum example

docs/index.rst

@@ -18,7 +18,8 @@ Features
 
 * Written in ANSI C99, compatible with ``size_t`` for size data types
 * Platform independent, no architecture specific code
-* Uses `LwRB <https://github.com/MaJerle/lwpkt>`_ library for data read/write operations
+* Uses `LwRB <https://github.com/MaJerle/lwrb>`_ library for data read/write operations
+* Support for events on packet ready, read or write operation
 * Optimized for embedded systems, allows high optimization for data transfer
 * Configurable settings for packet structure and variable data length
 * Allows multiple notes in network with `from` and `to` addresses

docs/requirements.txt

@@ -1,7 +1,7 @@
 breathe>=4.9.1
 colorama
-docutils>=0.14
-sphinx>=2.0.1
+docutils==0.16
+sphinx>=3.5.1
 sphinx_rtd_theme
 sphinx-tabs
 sphinxcontrib-svg2pdfconverter

examples/example_lwpkt_evt.c

@@ -99,7 +99,10 @@ example_lwpkt_evt(void) {
      * means we received data over network interface
      */
 
+    /* Set callback function */
+    lwpkt_set_evt_fn(&pkt, my_lwpkt_evt_fn);
+
     /* Now call process function instead */
     time = 100; /* Get_current_time_in_milliseconds */
-    lwpkt_process(&pkt, time, my_lwpkt_evt_fn);
+    lwpkt_process(&pkt, time);
 }

library.json

@@ -0,0 +1,31 @@
+{
+	"name": "LwPKT",
+	"version": "1.2.0",
+	"description": "Lightweight packet protocol library for communication implementation",
+	"keywords": "lwpkt, packet, protocol, manager, communication, com, lightweight, rs-485, rs-422, rs485, rs422, rs-232, rs232, uart, usart, lpuart",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/MaJerle/lwpkt.git"
+	},
+	"authors": [
+		{
+			"name": "Tilen Majerle",
+			"email": "tilen@majerle.eu",
+			"url": "https://majerle.eu"
+		}
+	],
+	"license": "MIT",
+	"homepage": "https://github.com/MaJerle/lwpkt",
+	"dependencies": {
+
+	},
+	"frameworks": "*",
+	"platforms": "*",
+	"export": {
+		"exclude": [
+			"docs",
+			"**/.vs",
+			"**/Debug"
+		]
+	}
+}

lwpkt/src/include/lwpkt/lwpkt.h

@@ -29,7 +29,7 @@
  * This file is part of LwPKT - Lightweight packet protocol library.
  *
  * Author:          Tilen MAJERLE <tilen@majerle.eu>
- * Version:         v1.1.0
+ * Version:         v1.2.0
  */
 #ifndef LWPKT_HDR_H
 #define LWPKT_HDR_H
@@ -54,18 +54,12 @@ extern "C" {
  */
 typedef enum {
     LWPKT_STATE_START = 0x00,                   /*!< Packet waits for start byte */
-#if LWPKT_CFG_USE_ADDR || __DOXYGEN__
     LWPKT_STATE_FROM,                           /*!< Packet waits for "packet from" byte */
     LWPKT_STATE_TO,                             /*!< Packet waits for "packet to" byte */
-#endif /* LWPKT_CFG_USE_ADDR || __DOXYGEN__ */
-#if LWPKT_CFG_USE_CMD || __DOXYGEN__
     LWPKT_STATE_CMD,                            /*!< Packet waits for "packet cmd" byte */
-#endif /* LWPKT_CFG_USE_CMD || __DOXYGEN__ */
     LWPKT_STATE_LEN,                            /*!< Packet waits for (multiple) data length bytes */
     LWPKT_STATE_DATA,                           /*!< Packet waits for actual data bytes */
-#if LWPKT_CFG_USE_CRC || __DOXYGEN__
     LWPKT_STATE_CRC,                            /*!< Packet waits for CRC data */
-#endif /* LWPKT_CFG_USE_CRC || __DOXYGEN__ */
     LWPKT_STATE_STOP,                           /*!< Packet waits for stop byte */
 } lwpkt_state_t;
 
@@ -80,6 +74,7 @@ typedef enum {
     lwpktERRCRC,                                /*!< CRC integrity error for the packet. Will not wait STOP byte if received */
     lwpktERRSTOP,                               /*!< Packet error with STOP byte, wrong character received for STOP */
     lwpktWAITDATA,                              /*!< Packet state is in start mode, waiting start byte to start receiving */
+    lwpktERRMEM,                                /*!< No enough memory available for write */
 } lwpktr_t;
 
 /**
@@ -89,6 +84,28 @@ typedef struct {
     uint8_t crc;                                /*!< Current CRC value */
 } lwpkt_crc_t;
 
+/* Forward declaration */
+struct lwpkt;
+
+/**
+ * \brief           List of event types
+ */
+typedef enum {
+    LWPKT_EVT_PKT,                              /*!< Valid packet ready to read */
+    LWPKT_EVT_TIMEOUT,                          /*!< Timeout on packat, reset event */
+    LWPKT_EVT_READ,                             /*!< Packet read operation.
+                                                         Called when read operation happens from RX buffer */
+    LWPKT_EVT_WRITE,                            /*!< Packet write operation.
+                                                         Called when write operation happens to TX buffer  */
+} lwpkt_evt_type_t;
+
+/**
+ * \brief           Event function prototype
+ * \param[in]       pkt: Packet structure
+ * \param[in]       evt_type: Event type
+ */
+typedef void (*lwpkt_evt_fn)(struct lwpkt* pkt, lwpkt_evt_type_t evt_type);
+
 /**
  * \brief           Device address data type
  */
@@ -101,14 +118,17 @@ typedef uint8_t lwpkt_addr_t;
 /**
  * \brief           Packet structure
  */
-typedef struct {
+typedef struct lwpkt {
 #if LWPKT_CFG_USE_ADDR || __DOXYGEN__
     lwpkt_addr_t addr;                          /*!< Current device address */
 #endif /* LWPKT_CFG_USE_ADDR || __DOXYGEN__ */
     uint8_t data[LWPKT_CFG_MAX_DATA_LEN];       /*!< Memory to write received data */
     LWRB_VOLATILE lwrb_t* tx_rb;                /*!< TX ringbuffer */
     LWRB_VOLATILE lwrb_t* rx_rb;                /*!< RX ringbuffer */
     uint32_t last_rx_time;                      /*!< Last RX time in units of milliseconds */
+#if LWPKT_CFG_USE_EVT || __DOXYGEN__
+    lwpkt_evt_fn evt_fn;                        /*!< Global event function for read and write operation */
+#endif /* LWPKT_CFG_USE_EVT || __DOXYGEN__ */
 
     struct {
         lwpkt_state_t state;                    /*!< Actual packet state machine */
@@ -127,21 +147,6 @@ typedef struct {
     } m;                                        /*!< Module that is periodically reset for next packet */
 } lwpkt_t;
 
-/**
- * \brief           List of event types
- */
-typedef enum {
-    LWPKT_EVT_PKT,                              /*!< Valid packet ready to read */
-    LWPKT_EVT_TIMEOUT                           /*!< Timeout on packat, reset event */
-} lwpkt_evt_type_t;
-
-/**
- * \brief           LwPKT event function
- * \param[in]       pkt: LwPKT instance with valid packet
- * \param[in]       type: Event type
- */
-typedef void(*lwpkt_evt_fn)(lwpkt_t* pkt, lwpkt_evt_type_t type);
-
 lwpktr_t    lwpkt_init(lwpkt_t* pkt, LWRB_VOLATILE lwrb_t* tx_rb, LWRB_VOLATILE lwrb_t* rx_rb);
 lwpktr_t    lwpkt_set_addr(lwpkt_t* pkt, lwpkt_addr_t addr);
 lwpktr_t    lwpkt_read(lwpkt_t* pkt);
@@ -154,7 +159,8 @@ lwpktr_t    lwpkt_write(lwpkt_t* pkt,
 #endif /* LWPKT_CFG_USE_CMD || __DOXYGEN__ */
     const void* data, size_t len);
 lwpktr_t    lwpkt_reset(lwpkt_t* pkt);
-lwpktr_t    lwpkt_process(lwpkt_t* pkt, uint32_t time, lwpkt_evt_fn evt_fn);
+lwpktr_t    lwpkt_process(lwpkt_t* pkt, uint32_t time);
+lwpktr_t    lwpkt_set_evt_fn(lwpkt_t* pkt, lwpkt_evt_fn evt_fn);
 
 /**
  * \brief           Get address from where packet was sent