404
+ +Page not found
+ + +'+ escapeHtml(title) + '
' + escapeHtml(summary) +'
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Extra functionality
+C++ Wrappers
+No exact statistics on C++ usage for embedded systems is available. However, the rough estimation is that somewhere between at least 20% and 50% of all embedded software projects make use of C++. Unfortunately, most embedded components and libraries do not take this into consideration.
+This is where MicroTBX-Modbus differs: Its C API was carefully crafted, such that easy-to-use C++ wrappers can encompass its entire functionality. In fact, it's actually easier to code with MicroTBX-Modbus in C++, compared to C. This section presents how to use the included C++ wrappers.
+Design
+The following illustration presents the UML class diagrams of the C++ wrappers:
+
Integration
+To add the C++ wrappers to your software project, complete the following steps:
+-
+
- Copy all files from the
source/extra/cplusplus/directory to your project.
+ - Configure your project such that the added
.cppfiles are compiled and linked during a build.
+ - Add the directories that contain the
.hppfiles to your compiler's include search path.
+
Alternatively, when using CMake to manager your project's build system, add microtbx-modbus-extra-cpp to its target_link_libraries() list.
Add the following lines to each source-file, where you intend to make use of MicroTBX-Modbus:
+#include <microtbx.h>
+#include <microtbxmodbus.hpp>
+Usage
+Similar to the getting started instructions, we'll take an empty C++ embedded software application as a starting point:
+#include "board.hpp"
+
+void main(void)
+{
+ /* Initialize the clock, enable peripherals and configure GPIO pins. */
+ Board::Init();
+
+ /* Enter the program's infinite loop. */
+ for(;;)
+ {
+
+ }
+}
+Modbus server
+We'll create a Modbus server step-by-step with the following properties:
+-
+
- Communication using serial communication in RTU mode: +
- Baudrate 19200 bits/second. +
- 8 data-bits +
- even parity +
- 1 stop-bit +
- Node address 10. +
- 1 coil at address 0 (element number 1), representing an LED. +
Create a new class, with a name of your choosing, which derives from TbxMbServerRtu. For example AppModbusServer and located in a header file called appmodbusserver.hpp. In the constructor's initializer list, call the base class constructor to specify the RTU specific properties:
#include <microtbx.h>
+#include <microtbxmodbus.hpp>
+
+class AppModbusServer : public TbxMbServerRtu
+{
+public:
+ AppModbusServer()
+ : TbxMbServerRtu(0x0A, TBX_MB_UART_PORT1, TBX_MB_UART_19200BPS,
+ TBX_MB_UART_1_STOPBITS, TBX_MB_EVEN_PARITY) { }
+ virtual ~AppModbusServer() { }
+};
+As a next step, we'll override method writeCoil and implement it such that this Modbus server changes the state of an LED, whenever it receives a coil write request at address 0:
#include <microtbx.h>
+#include <microtbxmodbus.hpp>
+
+class AppModbusServer : public TbxMbServerRtu
+{
+public:
+ AppModbusServer()
+ : TbxMbServerRtu(0x0A, TBX_MB_UART_PORT1, TBX_MB_UART_19200BPS,
+ TBX_MB_UART_1_STOPBITS, TBX_MB_EVEN_PARITY) { }
+ virtual ~AppModbusServer() { }
+
+ tTbxMbServerResult writeCoil(uint16_t addr, bool value) override
+ {
+ tTbxMbServerResult result = TBX_MB_SERVER_ERR_ILLEGAL_DATA_ADDR;
+
+ /* Request to write the coil at address 0? */
+ if (addr == 0U)
+ {
+ if (value == TBX_ON)
+ {
+ Board::LedOn();
+ }
+ else
+ {
+ Board::LedOff();
+ }
+ result = TBX_MB_SERVER_OK;
+ }
+ return result;
+ }
+};
+That's all there is to developing a Modbus server with the MicroTBX-Modbus C++ wrappers. To actually use this newly created class, create an instance of it and call the event task in the infinite program loop:
+#include "board.hpp"
+#include "appmodbusserver.hpp"
+
+void main(void)
+{
+ /* Initialize the clock, enable peripherals and configure GPIO pins. */
+ Board::Init();
+
+ /* Create Modbus server instance. */
+ AppModbusServer modbusServer;
+
+ /* Enter the program's infinite loop. */
+ for(;;)
+ {
+ /* Continuously call the Modbus stack event task function. */
+ TbxMbEvent::task();
+ }
+}
+Modbus client
+We'll build an application, which implements a Modbus client. It'll behave as the counter part to the Modbus server application. You could take the same approach, were you create a new class, which derives from TbxMbClientRtu. However, since this class does not contain any overridable methods, we can also just directly create a new instance of it:
TbxMbClientRtu modbusClient(1000U, 100U, TBX_MB_UART_PORT1, TBX_MB_UART_19200BPS,
+ TBX_MB_UART_1_STOPBITS, TBX_MB_EVEN_PARITY);
+With the help of method writeCoils, we can request the Modbus server at node address 10 to turn on its LED, located at coil address 0:
uint8_t coils[1] = { TBX_ON };
+
+modbusClient.writeCoils(10U, 0U, 1U, coils);
+Here follows the example application with all of this implemented, for completion purposes:
+#include <microtbx.h>
+#include <microtbxmodbus.hpp>
+#include "board.hpp"
+
+void main(void)
+{
+ uint8_t coils[1] = { TBX_ON };
+
+ /* Initialize the clock, enable peripherals and configure GPIO pins. */
+ Board::Init();
+
+ /* Create Modbus client instance. */
+ TbxMbClientRtu modbusClient(1000U, 100U, TBX_MB_UART_PORT1, TBX_MB_UART_19200BPS,
+ TBX_MB_UART_1_STOPBITS, TBX_MB_EVEN_PARITY);
+
+ /* Turn on one coil at address 0 on the server with node address 10. */
+ modbusClient.writeCoils(10U, 0U, 1U, coils);
+
+ /* Enter the program's infinite loop. */
+ for(;;)
+ {
+
+ }
+}
+Note that for a Modbus client that uses a superloop OSAL, there is no need to call TbxMbEvent::task(). The methods that communicate with the server block until the transmission completes and a response is received (if applicable). The event task is called internally while blocking.
Convenient and easy, but not optimal from a run-time performance perspective. For this reason, it is recommended to use an RTOS on the Modbus client, instead of a superloop type application. In the case of an RTOS, it is necessary to call TbxMbEvent::task() in a separate task that drives the Modbus stack.
+
+
+
+ GitHub
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/gettingstarted/index.html b/gettingstarted/index.html
new file mode 100644
index 0000000..54b45b7
--- /dev/null
+++ b/gettingstarted/index.html
@@ -0,0 +1,395 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Getting started
+If you're new to MicroTBX-Modbus, one of the first questions will be: How I do setup a Modbus server with it? The goal of this section is to answer exactly that question. As a starting point we'll take an empty embedded software application:
+#include "board.h"
+
+void main(void)
+{
+ /* Initialize the clock, enable peripherals and configure GPIO pins. */
+ BoardInit();
+
+ /* Enter the program's infinite loop. */
+ for(;;)
+ {
+
+ }
+}
+We'll create a Modbus server step-by-step with the following properties:
+-
+
- Communication using serial communication in RTU mode:
-
+
- Baudrate 19200 bits/second. +
- 8 data-bits +
- even parity +
- 1 stop-bit +
+ - Node address 10. +
- 1 coil at address 0 (element number 1), representing an LED. +
Construct the transport layer object
+The first step is always the construction of a transport layer object. It's the object that handles the actual transmission and reception of communication packets:
+/* Construct a Modbus RTU transport layer object. */
+tTbxMbTp modbusTp = TbxMbRtuCreate(10U, TBX_MB_UART_PORT1, TBX_MB_UART_19200BPS,
+ TBX_MB_UART_1_STOPBITS, TBX_MB_EVEN_PARITY);
+
+Construct the server channel object
+With the transport layer object created, we continue with constructing a server channel object and attaching the transport layer object to it:
+/* Construct a Modbus server object. */
+tTbxMbServer modbusServer = TbxMbServerCreate(modbusTp);
+Call the task function for event processing
+An event task function drives the MicroTBX-Modbus stack. We just need to continuously call it in the program's infinite superloop:
+/* Continuously call the Modbus stack event task function. */
+TbxMbEventTask();
+Configure the callback for handling coil writes
+Our example Modbus server should enable a Modbus client to change the state of an LED, whenever it receives a coil write request. For this we'll implement a callback function, with a name of our choosing, and then register this callback function for coil write requests:
+tTbxMbServerResult AppWriteCoil(tTbxMbServer channel, uint16_t addr, uint8_t value)
+{
+ tTbxMbServerResult result = TBX_MB_SERVER_OK;
+
+ /* Request to write the coil at address 0? */
+ if (addr == 0U)
+ {
+ if (value == TBX_ON)
+ {
+ BoardLedOn();
+ }
+ else
+ {
+ BoardLedOff();
+ }
+ }
+ /* Unsupported coil address. */
+ else
+ {
+ result = TBX_MB_SERVER_ERR_ILLEGAL_DATA_ADDR;
+ }
+ return result;
+}
+
+/* Set the callback for accessing the coils in the Modbus data table. */
+TbxMbServerSetCallbackWriteCoil(modbusServer, AppWriteCoil);
+Assembling it all together into our initial empty application results in this:
+#include <microtbx.h>
+#include <microtbxmodbus.h>
+#include "board.h"
+
+tTbxMbTp modbusTp;
+tTbxMbServer modbusServer;
+
+tTbxMbServerResult AppWriteCoil(tTbxMbServer channel, uint16_t addr, uint8_t value);
+
+void main(void)
+{
+ /* Initialize the clock, enable peripherals and configure GPIO pins. */
+ BoardInit();
+ /* Construct a Modbus RTU transport layer object. */
+ modbusTp = TbxMbRtuCreate(10, TBX_MB_UART_PORT1, TBX_MB_UART_19200BPS,
+ TBX_MB_UART_1_STOPBITS, TBX_MB_EVEN_PARITY);
+ /* Construct a Modbus server object. */
+ modbusServer = TbxMbServerCreate(modbusTp);
+ /* Set the callback for accessing the coils in the Modbus data table. */
+ TbxMbServerSetCallbackWriteCoil(modbusServer, AppWriteCoil);
+
+ /* Enter the program's infinite loop. */
+ for(;;)
+ {
+ /* Continuously call the Modbus stack event task function. */
+ TbxMbEventTask();
+ }
+}
+
+tTbxMbServerResult AppWriteCoil(tTbxMbServer channel, uint16_t addr, uint8_t value)
+{
+ tTbxMbServerResult result = TBX_MB_SERVER_ERR_ILLEGAL_DATA_ADDR;
+
+ /* Request to write the coil at address 0? */
+ if (addr == 0U)
+ {
+ if (value == TBX_ON)
+ {
+ BoardLedOn();
+ }
+ else
+ {
+ BoardLedOff();
+ }
+ result = TBX_MB_SERVER_OK;
+ }
+ return result;
+}
+And voilà, you now have a fully functional Modbus server. You can extend it by adding support for:
+-
+
- Writing holding registers. +
- Reading discrete inputs. +
- Reading input registers. +
The process is the same: You implement the callback function and then register it with the channel using a TbxMbServerSetCallbackXxx() API function. Refer to the API reference for more details.
Using FreeRTOS instead of a superloop
+The previous example assumed a traditional superloop type application. Thanks to the ever increasing processing power and available RAM and ROM memory on modern microcontrollers, the use of a real-time operating system (RTOS) is more common.
+For this reason, MicroTBX-Modbus ships with an operating system abstraction layer (OSAL). In this section, we'll upgrade the previous superloop example to use FreeRTOS instead of a traditional superloop.
+Select the correct OSAL source file
+As a first step, re-configure your project to compile and link the correct OSAL source file:
+-
+
- Remove
source/osal/tbxmb_superloop.cfrom your project.
+ - Add
source/osal/tbxmb_freertos.cto your project.
+
In case you use CMake to manage your project's build system, update its target_link_libraries():
-
+
- Remove
microtbx-modbus-osal-superloop.
+ - Add
microtbx-modbus-osal-freertos.
+
Create a new RTOS task for event handling
+Instead of continuously calling TbxMbEventTask() in the superloop, create a new RTOS task and call TbxMbEventTask() in the task's infinite loop. You can assign it a priority of your liking that fits your application. Note that the MicroTBX-Modbus FreeRTOS OSAL source file automatically places the RTOS task in the waiting state, when no events are pending:
void AppModbusTask(void * pvParameters)
+{
+ /* Enter infinite task loop. */
+ for (;;)
+ {
+ /* Continuously call the Modbus stack event task function. */
+ TbxMbEventTask();
+ }
+}
+
+/* Create the Modbus task. */
+xTaskCreate(AppModbusTask, "ModbusTask", configMINIMAL_STACK_SIZE, NULL, 4U, NULL);
+Here follows to previous example application, upgraded for FreeRTOS:
+#include <microtbx.h>
+#include <microtbxmodbus.h>
+#include "board.h"
+#include "FreeRTOS.h"
+#include "task.h"
+
+tTbxMbTp modbusTp;
+tTbxMbServer modbusServer;
+
+void AppModbusTask(void * pvParameters);
+tTbxMbServerResult AppWriteCoil(tTbxMbServer channel, uint16_t addr, uint8_t value);
+
+void main(void)
+{
+ /* Initialize the clock, enable peripherals and configure GPIO pins. */
+ BoardInit();
+ /* Construct a Modbus RTU transport layer object. */
+ modbusTp = TbxMbRtuCreate(10, TBX_MB_UART_PORT1, TBX_MB_UART_19200BPS,
+ TBX_MB_UART_1_STOPBITS, TBX_MB_EVEN_PARITY);
+ /* Construct a Modbus server object. */
+ modbusServer = TbxMbServerCreate(modbusTp);
+ /* Set the callback for accessing the coils in the Modbus data table. */
+ TbxMbServerSetCallbackWriteCoil(modbusServer, AppWriteCoil);
+ /* Create the Modbus task. */
+ xTaskCreate(AppModbusTask, "ModbusTask", configMINIMAL_STACK_SIZE, NULL, 4U, NULL);
+ /* Start the RTOS scheduler. Note that this function does not return. */
+ vTaskStartScheduler();
+}
+
+void AppModbusTask(void * pvParameters)
+{
+ /* Enter infinite task loop. */
+ for (;;)
+ {
+ /* Continuously call the Modbus stack event task function. */
+ TbxMbEventTask();
+ }
+}
+
+tTbxMbServerResult AppWriteCoil(tTbxMbServer channel, uint16_t addr, uint8_t value)
+{
+ tTbxMbServerResult result = TBX_MB_SERVER_ERR_ILLEGAL_DATA_ADDR;
+
+ /* Request to write the coil at address 0? */
+ if (addr == 0U)
+ {
+ if (value == TBX_ON)
+ {
+ BoardLedOn();
+ }
+ else
+ {
+ BoardLedOff();
+ }
+ result = TBX_MB_SERVER_OK;
+ }
+ return result;
+}
+Next steps
+After reading through this getting started section, you now have a basic understanding of how to set up a Modbus server. For ready-to-run examples, refer to the demo programs in the separate repository. It also includes example on how to set up a Modbus client, instead of a server:
+ +For more in-depth details on the API functions offered by MicroTBX-Modbus, head over to the API reference in this user manual. When your itchy to start adding MicroTBX-Modbus to your own embedded software program, continue with the integration section of this user manual.
+ +
+
+
+
+ GitHub
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/images/uml_class_diagram.png b/images/uml_class_diagram.png
new file mode 100644
index 0000000..2eaa0a3
Binary files /dev/null and b/images/uml_class_diagram.png differ
diff --git a/images/uml_class_diagram.uxf b/images/uml_class_diagram.uxf
new file mode 100644
index 0000000..81d7121
--- /dev/null
+++ b/images/uml_class_diagram.uxf
@@ -0,0 +1,230 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/integration/index.html b/integration/index.html
new file mode 100644
index 0000000..155efb6
--- /dev/null
+++ b/integration/index.html
@@ -0,0 +1,214 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Introduction to MicroTBX-Modbus
+MicroTBX-Modbus is a modern Modbus communication stack, targeting microcontroller based embedded systems. Its aim is to be: easy to use, easy to port, high quality, well maintained, stable and flexible. The ideal solution for any embedded software engineer, with an interest in adding Modbus communication to their product.
+Features
+-
+
- Carefully crafted application programming interface (API), focusing on ease of use. +
- Written in the C programming language (C99) with high MISRA compliance. +
- Supports both Modbus client and Modbus server functionality. +
- Supports multi channel for both the Modbus client and server. +
- Flexible dual licensing model. +
- Designed such that it can be used with and without and RTOS. +
- Easy to integrate into existing software projects, especially when using CMake. +
- Includes C++ wrappers for those preferring to develop in an object-oriented manner. +
- Quick and simple to adjust to your microcontroller system. +
- No compile-time configuration needed. +
- Option to implement additional and custom Modbus function codes. +
Supported function codes
+MicroTBX-Modbus currently supports the following Modbus function codes:
+| Function Code | +Name | +
|---|---|
| 1 | +Read Coils | +
| 2 | +Read Discrete Inputs | +
| 3 | +Read Holding Registers | +
| 4 | +Read Input Registers | +
| 5 | +Write Single Coil | +
| 6 | +Write Single Register | +
| 8 | +Diagnostics (sub codes: 0, 10, 11, 12, 13, 14, 15) | +
| 15 | +Write Multiple Coils | +
| 16 | +Write Multiple Registers | +
Note that MicroTBX-Modbus includes functionality, enabling you to extend it by adding support for additional and custom function codes.
+Why another Modbus stack?
+With Modbus being such a convenient and mature communication protocol, several other Modbus software stacks exist; Both closed sourced and open sourced. Why bother with developing and maintaining yet another one? It turns out that most of the existing ones all seem to be limiting on at least one front:
+-
+
- No multi-channel support. +
- Not including both client and server functionality. +
- Not being able to add support for additional and custom function codes. +
- Skipping features needed for protocol compliance. +
- No open source option. +
- Not actively maintained. +
MicroTBX-Modbus addresses all these limitations. Thanks to the flexible dual licensing model, you can start out right away with the open source GPLv3 version. Perfect for testing, evaluation and prototyping purposes. Once you're satisfied with it and would like to include MicroTBX-Modbus in your proprietary closed sourced product, you can move on to the commercial license.
+The only reason not to use MicroTBX-Modbus is that it currently only supports Modbus RTU communication. Note though that support for ASCII and TCP communication is planned for the future.
+System requirements
+With MicroTBX-Modbus being a modern communication stack, the focus is more on ease and flexibility of use for the developer, and less on keeping the ROM footprint low. Therefore the recommended system requirements are slightly higher than comparative Modbus software solutions:
+It is recommended to use a microcontroller with at least 32 KiB flash and 4 KiB RAM. However, it will run on a basic 8-bit microcontroller with just 10 KiB of flash and 1.5 KiB RAM. Although you then run out of storage space quickly, when adding your own firmware’s functionality.
+Next steps
+The getting started section of this user manual shows you how to quickly setup a Modbus server and client. Definitely worth a glance if you're new to MicroTBX-Modbus.
+For those who want to see MicroTBX-Modbus in action, you can find ready-to-run demo programs located in a separate repository. These demo programs target an ever growing collection of popular microcontroller evaluation boards and serve as a good starting point:
+ +If you're ready to integrate MicroTBX-Modbus into your own embedded software project, head over to the integration section of this user manual for detailed instructions.
+MicroTBX-Modbus itself is hardware independent. To handle the hardware specifics of your microcontroller, you just need to implement a few port functions. A template source-file is provided. You can find detailed instructions in the portation section of this user manual.
+Once you got everything up-and-running and would like to use MicroTBX-Modbus in the closed source proprietary firmware of your product, make sure to upgrade to the commercial license. The default GPLv3 licensed version is not suitable for that use case.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Integration
+To make the MicroTBX-Modbus functionality available to your embedded software project, you need to integrate its source code into your project. This section of the user manual walks you through this process step-by-step. It covers two integration approaches:
+-
+
-
+
Classical integration, where you add the source files manually to your project and configure your build environment accordingly.
+
+ -
+
CMake integration, where you leverage the power of CMake to do the heavy-lifting.
+
+
As a reference, you can look at the separate repository with MicroTBX-Modbus demo programs. It includes demo programs for different microcontroller boards that are preconfigured and already have MicroTBX-Modbus fully integrated.
+Prerequisites
+Since MicroTBX-Modbus builds upon the MicroTBX base component, make sure you already integrated the MicroTBX base component into your embedded software project. You can find the MicroTBX integration instructions in the MicroTBX user manual.
+Classical integration
+Adding MicroTBX-Modbus to your software project is a simple five step process:
+-
+
- Copy all files from the
sourcedirectory to your project.
+ - Copy the
source/template/tbxmb_port.cport template source file to your project.
+ - Copy the
source/osal/tbxmb_XXX.cfor your selected operating system to your project.
+ - Configure your project such that the added
.cfiles are compiled and linked during a build.
+ - Add the directories that contain the
.hfiles to your compiler's include search path.
+
CMake integration
+The use of CMake to manage the build environment rapidly gains popularity among embedded software developers. It makes adding third-party libraries, such as MicroTBX-Modbus, a breeze:
+-
+
- Copy the entire MicroTBX-Modbus directory into your project. Manually or as a Git submodule. +
- Use
add_subdirectory()to register the MicroTBX-Modbus interface library.
+ - Copy the
source/template/tbxmb_port.cport template source file to your project and add it as a source file toadd_executable().
+ - Add the
microtbx-modbusinterface library totarget_link_libraries().
+ - Add the
microtbx-modbus-osal-XXXinterface library for your selected operating system totarget_link_libraries().
+
Minimal CMakeLists.txt example, if you copied MicroTBX-Modbus to directory third_party/microtbx-modbus:
project(MyProject)
+
+add_subdirectory(third_party/microtbx-modbus)
+
+add_executable(MyProject
+ main.c
+ tbxmb_port.c
+)
+
+target_link_libraries(MyProject
+ microtbx-modbus
+ microtbx-modbus-osal-superloop
+)
+Adjust the port
+The MicroTBX-Modbus source code itself is fully hardware independent. The tbxmb_port.c port source file implements the hardware specifics. This means that you only need to update this source file, to get MicroTBX-Modbus working on your specific microcontroller system. You can find detailed instructions, on how to port MicroTBX-Modbus to your platform, in the portation section of this user manual.
Usage
+Add the following lines to each source-file, where you intend to make use of MicroTBX-Modbus:
+#include <microtbx.h>
+#include <microtbxmodbus.h>
+
+
+
+
+ GitHub
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/js/html5shiv.min.js b/js/html5shiv.min.js
new file mode 100644
index 0000000..1a01c94
--- /dev/null
+++ b/js/html5shiv.min.js
@@ -0,0 +1,4 @@
+/**
+* @preserve HTML5 Shiv 3.7.3 | @afarkas @jdalton @jon_neal @rem | MIT/GPL2 Licensed
+*/
+!function(a,b){function c(a,b){var c=a.createElement("p"),d=a.getElementsByTagName("head")[0]||a.documentElement;return c.innerHTML="x",d.insertBefore(c.lastChild,d.firstChild)}function d(){var a=t.elements;return"string"==typeof a?a.split(" "):a}function e(a,b){var c=t.elements;"string"!=typeof c&&(c=c.join(" ")),"string"!=typeof a&&(a=a.join(" ")),t.elements=c+" "+a,j(b)}function f(a){var b=s[a[q]];return b||(b={},r++,a[q]=r,s[r]=b),b}function g(a,c,d){if(c||(c=b),l)return c.createElement(a);d||(d=f(c));var e;return e=d.cache[a]?d.cache[a].cloneNode():p.test(a)?(d.cache[a]=d.createElem(a)).cloneNode():d.createElem(a),!e.canHaveChildren||o.test(a)||e.tagUrn?e:d.frag.appendChild(e)}function h(a,c){if(a||(a=b),l)return a.createDocumentFragment();c=c||f(a);for(var e=c.frag.cloneNode(),g=0,h=d(),i=h.length;i>g;g++)e.createElement(h[g]);return e}function i(a,b){b.cache||(b.cache={},b.createElem=a.createElement,b.createFrag=a.createDocumentFragment,b.frag=b.createFrag()),a.createElement=function(c){return t.shivMethods?g(c,a,b):b.createElem(c)},a.createDocumentFragment=Function("h,f","return function(){var n=f.cloneNode(),c=n.createElement;h.shivMethods&&("+d().join().replace(/[\w\-:]+/g,function(a){return b.createElem(a),b.frag.createElement(a),'c("'+a+'")'})+");return n}")(t,b.frag)}function j(a){a||(a=b);var d=f(a);return!t.shivCSS||k||d.hasCSS||(d.hasCSS=!!c(a,"article,aside,dialog,figcaption,figure,footer,header,hgroup,main,nav,section{display:block}mark{background:#FF0;color:#000}template{display:none}")),l||i(a,d),a}var k,l,m="3.7.3",n=a.html5||{},o=/^<|^(?:button|map|select|textarea|object|iframe|option|optgroup)$/i,p=/^(?:a|b|code|div|fieldset|h1|h2|h3|h4|h5|h6|i|label|li|ol|p|q|span|strong|style|table|tbody|td|th|tr|ul)$/i,q="_html5shiv",r=0,s={};!function(){try{var a=b.createElement("a");a.innerHTML="
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Dual licensing model
+By default, MicroTBX-Modbus is licensed under version 3 of the GNU GPL (GPLv3). Thanks to the GPLv3, MicroTBX-Modbus can be released with full source code and is perfect for these use cases:
+-
+
- Evaluation, education, prototyping, hobbying and inclusion in other open source projects. +
The GPLv3 licensed version of MicroTBX-Modbus is not suitable for these use cases:
+-
+
- Inclusion in closed source proprietary firmware. +
To circumvent the restrictions and responsibilities that come with the GPLv3, your company can purchase a commercially licensed version of MicroTBX-Modbus. With your commercially licensed version of MicroTBX-Modbus, you can include and make use of this software in your closed source proprietary firmware.
+License comparison
+Refer to the following license comparison matrix to decide on the suitable MicroTBX-Modbus license for your product:
+| Question | +GNU GPL version 3 | +Commercial license | +
|---|---|---|
| Is MicroTBX-Modbus free? | +yes | +no | +
| Do I have the right to change the MicroTBX-Modbus source code? |
+yes | +yes | +
| Can I use MicroTBX-Modbus in my closed source product? |
+no | +yes | +
| Do I have to open my source code? | +yes | +no | +
| Do I have to open source my changes to MicroTBX-Modbus? |
+yes | +no | +
| Do I have to offer the MicroTBX-Modbus source code to users of my product? |
+yes | +no | +
| Do I have to document that my product uses MicroTBX-Modbus? |
+yes | +no | +
| Can I redistribute MicroTBX-Modbus in source code format? |
+yes | +no | +
| Can I receive professional technical support on a commercial basis? |
+no | +yes | +
Why a dual licensing model?
+The development and maintenance, needed to make available a stable, high quality and open source embedded software component, takes significant engineering time and effort. From experience with the OpenBLT bootloader, Feaser learned that relying solely on donations is unfortunately not a viable and sustainable option. The dual licensing model offers the best of both worlds, making it a win-win scenario for all its users:
+-
+
- It makes it possible for MicroTBX-Modbus to be available to everyone as open source. +
- The income generated from the commercial license sales enables Feaser to sponsor the long-term development and maintenance of MicroTBX-Modbus. +
How to purchase the commercial license?
+To purchase the commercial license, contact Feaser to request a quote. Based on the quote, you can generate and e-mail us your purchase order. You can expect to receive an order confirmation within one business days. Afterwards, Feaser starts working on putting together your commercially licensed MicroTBX-Modbus software package, which will be delivered to you electronically.
+Licensing frequently asked questions
+What happens if I do include the GPLv3 version of MicroTBX-Modbus in my own software?
+As long as you do not distribute your software to someone else, nothing really happens. However, the moment you either give or sell your software or a product containing your software, you are required to open source the source code of your entire software. The GPLv3 is infectious; any code that uses GPLv3 software, automatically becomes GPLv3 as well.
+Are there any differences between the GPLv3 and commercially licensed versions of MicroTBX-Modbus?
+The only changes are the license text in the license file and the license information in the source files. The actual API and functionality of MicroTBX-Modbus is exactly the same.
+What are the restrictions of the MicroTBX-Modbus commercial license?
+The only real restriction of the commercial license is that you cannot redistribute your commercially licensed version of MicroTBX-Modbus to third parties in source code format (including your customers and users). Binary format (object-code or executable) is of course allowed. Feel free to contact Feaser to request a sample of the commercial license for you to review.
+Do I need to pay additional royalties?
+The commercial license is a one-time fee. Once you purchased it, your company can include MicroTBX-Modbus in all its products, without having to pay per-unit royalties.
+How can I obtain pricing information for the commercial license for MicroTBX-Modbus?
+E-mail Feaser a quote request and we'll send you a quote, which includes pricing information.
+What do I receive after purchasing the MicroTBX-Modbus commercial license?
+After reception of your purchase order, you'll receive an order confirmation typically within one business day. Afterwards we'll prepare your commercially licensed version of MicroTBX-Modbus and deliver it to you electronically. Estimated delivery time is within a few days.
+How can I pay for the MicroTBX-Modbus commercial license?
+Invoicing takes place after delivery of your commercially licensed version of MicroTBX-Modbus. Payment can be made via direct bank transfer or online by credit card. Detailed payment information is included on the invoice.
+ +
+
+
+
+ GitHub
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/misra/index.html b/misra/index.html
new file mode 100644
index 0000000..b74caef
--- /dev/null
+++ b/misra/index.html
@@ -0,0 +1,177 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ MISRA compliance
+Static code analysis was performed to verify compliance with MISRA-C 2012. This document lists the compliance exceptions:
+Global
+| Directive | +Type | +Rationale | +
|---|---|---|
| 2.5 | +advisory | +Especially in reusable modules or peripheral drivers, macro definitions can remain unused in the module or driver itself, but should be kept for the end-user. For example version macros and configuration options. |
+
| 11.5 | +advisory | +Conversions from pointer to void to pointer to other type. This is needed after allocating memory from the heap and then initializing a pointer to point to this allocated memory. Used for example when allocating memory to build a linked list. |
+
+
+
+
+ GitHub
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/portation/index.html b/portation/index.html
new file mode 100644
index 0000000..d4f796f
--- /dev/null
+++ b/portation/index.html
@@ -0,0 +1,360 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Porting to your microcontroller platform
+MicroTBX-Modbus comes with a build-in hardware abstraction layer. Essentially, this means that you only need to adjust the implementation of a few functions, to get the communication stack working on your specific microcontroller system. You can find a framework for all these functions at this location:
+-
+
source/template/tbxmb_port.c
+
Furthermore, the demo programs, located in a separate repository, already include ready-made ports:
+ +When tasked with getting MicroTBX-Modbus running on your specific microcontroller system, follow these steps:
+-
+
- First check if demo programs exists for a microcontroller similar to yours. If so, grab that version of
tbxmb_port.cand make whatever little tweaks needed to adjust it for your microcontroller system. Chances are that it already works, without making any changes.
+ - Otherwise, grab the
tbxmb_port.cfile from thesource/template/directory and use it as a starting point. Check the source code comments that lead withTODO ##Port. They contain hints about what you need to implement.
+
The remainder of this section explains in more detail how to implement the port functions. Note that you can also outsource this effort to Feaser.
+Timer
+MicroTBX-Modbus needs a time reference. For example to monitor the RTU communication's 1.5 and 3.5 character times. To get these timings right a free running counter, incrementing every 50 microseconds, provides a time reference.
+TbxMbPortTimerCount
+uint16_t TbxMbPortTimerCount(void)
+This function obtains the current value of this counter and assumes that you already initialized a timer, during application initialization, to have its free running counter counting upwards at a 20 kHz frequency.
+In contrast to most other Modbus communication stacks, MicroTBX-Modbus does not rely on an interrupt driven timer. It just needs the value of a timer peripheral's counter register, initialized to count upwards once every 50 microseconds. Benefits of this approach are that it has no interrupt overhead and that you can still reuse the timer for other purposes (input capture, PWM, output compare, etc.), as long as it can work with a 20 kHz base timer.
+Timers are a scarce resource on microcontrollers. Therefore it is also possible to use the free running counter of a timer that runs at a different frequency. Just make sure to adjust the counter value in this function accordingly. For example, if you choose to reuse your RTOS' 1 millisecond system tick, you need to multiply its tick counter value by 20 to simulate a 20 kHz timer. This does of course have a negative impact on the accuracy of the RTU 1.5 and 3.5 character timings, so there's a trade-off involved.
+| Return value | +
|---|
| Free running counter value as a 16-bit value. If your timer's counter value is more than 16-bit, simply typecast it to uint16_t. |
+
UART
+The RTU and ASCII transport layers depend on a UART communication peripheral for the low-level data exchange. It is recommended to use a classical approach, where the transmission completion and reception of each byte triggers an interrupt.
+You could leverage the capability of a direct memory access (DMA) peripheral, in combination with the UART, as this lowers the interrupt overhead. However, this should not be used for data reception in combination with an RTU transport layer. The 1.5 character time between bytes can then not be properly monitored. DMA can be used for transmission, but the processing time of the byte transmit complete event is very short and therefore dedicating a DMA just for this is probably not worth it.
+TbxMbPortUartInit
+void TbxMbPortUartInit(tTbxMbUartPort port,
+ tTbxMbUartBaudrate baudrate,
+ tTbxMbUartDatabits databits,
+ tTbxMbUartStopbits stopbits,
+ tTbxMbUartParity parity)
+Initialize the UART channel by performing the following steps:
+-
+
- Enable the clock of the UART peripheral. +
- Configure the UART Rx and Tx GPIO pins for UART communication. +
- Switch the RS485 transceiver to reception mode (DE/NRE pins), if used. +
- Configure the baudrate, number of databits, number of stopbits, and parity mode. +
- Enable the UART transmitter and receiver. +
- Enable the receive data register full (RXNE) interrupt. +
Note that the actual meaning of the serial port number (port) is up to you. It typically maps to the UART peripheral number. E.g. TBX_MB_UART_PORT1 = USART1 on an STM32. However, it doesn't have to. Let's say you only use two UART peripherals on your microcontroller system: USART2 and USART6. In this case it makes logical sense to map TBX_MB_UART_PORT1 to USART2 and TBX_MB_UART_PORT2 to USART6.
| Parameter | +Description | +
|---|---|
port |
+The serial port to use. | +
baudrate |
+The desired communication speed. | +
databits |
+Number of databits for a character. | +
stopbits |
+Number of stop bits at the end of a character. | +
parity |
+Parity bit type to use. | +
TbxMbPortUartTransmit
+uint8_t TbxMbPortUartTransmit(tTbxMbUartPort port,
+ uint8_t const * data,
+ uint16_t len)
+Start the transfer of len bytes from the data array on the specified serial port:
-
+
- Switch the RS485 transceiver to transmission mode (DE/NRE pins), if used. +
- Write the first byte (
data[0]) to the UART transmit data register.
+ - Enable the transmit complete (TC) interrupt if the total length is just one byte (
lenis 1), otherwise enable the transmit data register empty (TXE) interrupt.
+
For managing the entire transfer, It is recommended to save transfer related information in a global (volatile) variable. It can then be accessed and updated in the transmit interrupt handler (TbxMbPortUartTxInterrupt()). This is what the template does with the transmitInfo[] array.
Note that you have mutual exclusive access to the bytes in the data array, until you call TbxMbUartTransmitComplete(). This means that you do not need to copy the data bytes to a local buffer. This approach keeps RAM requirements low and benefits the run-time performance. Just make sure to call TbxMbUartTransmitComplete() once all bytes are transmitted or an error was detected, to release access to the data array.
| Parameter | +Description | +
|---|---|
port |
+The serial port to start the data transfer on. | +
data |
+Byte array with data to transmit. | +
len |
+Number of bytes to transmit. | +
| Return value | +
|---|
TBX_OK if successful, TBX_ERROR otherwise. |
+
TbxMbPortUartTxInterrupt
+void TbxMbPortUartTxInterrupt(tTbxMbUartPort port)
+UART transmit complete and data register empty interrupt handler. Should be called from your UART interrupt handler, upon detection of this event, and do the following:
+-
+
- If no more bytes are left to transmit:
-
+
- Disable the transmit complete (TC) interrupt. +
- Switch the RS485 transceiver to reception mode (DE/NRE pins), if used. +
- Call TbxMbUartTransmitComplete() of the Modbus UART module to release mutual exclusive access to the transmit data buffer. +
+ - Otherwise, write the next byte to the UART transmit data register.
-
+
- If this is the last byte of the transfer:
-
+
- Disable the transmit data register empty (TXE) interrupt. +
- Enable the transmit complete (TC) interrupt. +
+
+ - If this is the last byte of the transfer:
| Parameter | +Description | +
|---|---|
port |
+The serial port that generated the interrupt. | +
TbxMbPortUartRxInterrupt
+void TbxMbPortUartRxInterrupt(tTbxMbUartPort port)
+UART reception data register full interrupt handler. Should be called from your UART interrupt handler, upon detection of this event, and do the following:
+-
+
- If a parity, framing or noise error was detected during the data reception, ignore the newly received byte. +
- Clear all error reception related error flags: parity, framing, noise and also reception overrun. +
- Read the newly received data from the UART reception data register. +
- Clear the reception data register empty flag, if the UART peripheral does not automatically do this after a read from the UART reception data register. +
- If the newly received byte should not be ignored, inform the Modbus UART module about the event, by calling TbxMbUartDataReceived(). +
| Parameter | +Description | +
|---|---|
port |
+The serial port that generated the interrupt. | +
+
+
+
+ GitHub
+
+
+
+ « Previous
+
+
+ Next »
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/search.html b/search.html
new file mode 100644
index 0000000..cf0f10e
--- /dev/null
+++ b/search.html
@@ -0,0 +1,144 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Search Results
+ + + +
+ Searching...
+
+
+
+
+
+
+
+ GitHub
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/search/lunr.js b/search/lunr.js
new file mode 100644
index 0000000..aca0a16
--- /dev/null
+++ b/search/lunr.js
@@ -0,0 +1,3475 @@
+/**
+ * lunr - http://lunrjs.com - A bit like Solr, but much smaller and not as bright - 2.3.9
+ * Copyright (C) 2020 Oliver Nightingale
+ * @license MIT
+ */
+
+;(function(){
+
+/**
+ * A convenience function for configuring and constructing
+ * a new lunr Index.
+ *
+ * A lunr.Builder instance is created and the pipeline setup
+ * with a trimmer, stop word filter and stemmer.
+ *
+ * This builder object is yielded to the configuration function
+ * that is passed as a parameter, allowing the list of fields
+ * and other builder parameters to be customised.
+ *
+ * All documents _must_ be added within the passed config function.
+ *
+ * @example
+ * var idx = lunr(function () {
+ * this.field('title')
+ * this.field('body')
+ * this.ref('id')
+ *
+ * documents.forEach(function (doc) {
+ * this.add(doc)
+ * }, this)
+ * })
+ *
+ * @see {@link lunr.Builder}
+ * @see {@link lunr.Pipeline}
+ * @see {@link lunr.trimmer}
+ * @see {@link lunr.stopWordFilter}
+ * @see {@link lunr.stemmer}
+ * @namespace {function} lunr
+ */
+var lunr = function (config) {
+ var builder = new lunr.Builder
+
+ builder.pipeline.add(
+ lunr.trimmer,
+ lunr.stopWordFilter,
+ lunr.stemmer
+ )
+
+ builder.searchPipeline.add(
+ lunr.stemmer
+ )
+
+ config.call(builder, builder)
+ return builder.build()
+}
+
+lunr.version = "2.3.9"
+/*!
+ * lunr.utils
+ * Copyright (C) 2020 Oliver Nightingale
+ */
+
+/**
+ * A namespace containing utils for the rest of the lunr library
+ * @namespace lunr.utils
+ */
+lunr.utils = {}
+
+/**
+ * Print a warning message to the console.
+ *
+ * @param {String} message The message to be printed.
+ * @memberOf lunr.utils
+ * @function
+ */
+lunr.utils.warn = (function (global) {
+ /* eslint-disable no-console */
+ return function (message) {
+ if (global.console && console.warn) {
+ console.warn(message)
+ }
+ }
+ /* eslint-enable no-console */
+})(this)
+
+/**
+ * Convert an object to a string.
+ *
+ * In the case of `null` and `undefined` the function returns
+ * the empty string, in all other cases the result of calling
+ * `toString` on the passed object is returned.
+ *
+ * @param {Any} obj The object to convert to a string.
+ * @return {String} string representation of the passed object.
+ * @memberOf lunr.utils
+ */
+lunr.utils.asString = function (obj) {
+ if (obj === void 0 || obj === null) {
+ return ""
+ } else {
+ return obj.toString()
+ }
+}
+
+/**
+ * Clones an object.
+ *
+ * Will create a copy of an existing object such that any mutations
+ * on the copy cannot affect the original.
+ *
+ * Only shallow objects are supported, passing a nested object to this
+ * function will cause a TypeError.
+ *
+ * Objects with primitives, and arrays of primitives are supported.
+ *
+ * @param {Object} obj The object to clone.
+ * @return {Object} a clone of the passed object.
+ * @throws {TypeError} when a nested object is passed.
+ * @memberOf Utils
+ */
+lunr.utils.clone = function (obj) {
+ if (obj === null || obj === undefined) {
+ return obj
+ }
+
+ var clone = Object.create(null),
+ keys = Object.keys(obj)
+
+ for (var i = 0; i < keys.length; i++) {
+ var key = keys[i],
+ val = obj[key]
+
+ if (Array.isArray(val)) {
+ clone[key] = val.slice()
+ continue
+ }
+
+ if (typeof val === 'string' ||
+ typeof val === 'number' ||
+ typeof val === 'boolean') {
+ clone[key] = val
+ continue
+ }
+
+ throw new TypeError("clone is not deep and does not support nested objects")
+ }
+
+ return clone
+}
+lunr.FieldRef = function (docRef, fieldName, stringValue) {
+ this.docRef = docRef
+ this.fieldName = fieldName
+ this._stringValue = stringValue
+}
+
+lunr.FieldRef.joiner = "/"
+
+lunr.FieldRef.fromString = function (s) {
+ var n = s.indexOf(lunr.FieldRef.joiner)
+
+ if (n === -1) {
+ throw "malformed field ref string"
+ }
+
+ var fieldRef = s.slice(0, n),
+ docRef = s.slice(n + 1)
+
+ return new lunr.FieldRef (docRef, fieldRef, s)
+}
+
+lunr.FieldRef.prototype.toString = function () {
+ if (this._stringValue == undefined) {
+ this._stringValue = this.fieldName + lunr.FieldRef.joiner + this.docRef
+ }
+
+ return this._stringValue
+}
+/*!
+ * lunr.Set
+ * Copyright (C) 2020 Oliver Nightingale
+ */
+
+/**
+ * A lunr set.
+ *
+ * @constructor
+ */
+lunr.Set = function (elements) {
+ this.elements = Object.create(null)
+
+ if (elements) {
+ this.length = elements.length
+
+ for (var i = 0; i < this.length; i++) {
+ this.elements[elements[i]] = true
+ }
+ } else {
+ this.length = 0
+ }
+}
+
+/**
+ * A complete set that contains all elements.
+ *
+ * @static
+ * @readonly
+ * @type {lunr.Set}
+ */
+lunr.Set.complete = {
+ intersect: function (other) {
+ return other
+ },
+
+ union: function () {
+ return this
+ },
+
+ contains: function () {
+ return true
+ }
+}
+
+/**
+ * An empty set that contains no elements.
+ *
+ * @static
+ * @readonly
+ * @type {lunr.Set}
+ */
+lunr.Set.empty = {
+ intersect: function () {
+ return this
+ },
+
+ union: function (other) {
+ return other
+ },
+
+ contains: function () {
+ return false
+ }
+}
+
+/**
+ * Returns true if this set contains the specified object.
+ *
+ * @param {object} object - Object whose presence in this set is to be tested.
+ * @returns {boolean} - True if this set contains the specified object.
+ */
+lunr.Set.prototype.contains = function (object) {
+ return !!this.elements[object]
+}
+
+/**
+ * Returns a new set containing only the elements that are present in both
+ * this set and the specified set.
+ *
+ * @param {lunr.Set} other - set to intersect with this set.
+ * @returns {lunr.Set} a new set that is the intersection of this and the specified set.
+ */
+
+lunr.Set.prototype.intersect = function (other) {
+ var a, b, elements, intersection = []
+
+ if (other === lunr.Set.complete) {
+ return this
+ }
+
+ if (other === lunr.Set.empty) {
+ return other
+ }
+
+ if (this.length < other.length) {
+ a = this
+ b = other
+ } else {
+ a = other
+ b = this
+ }
+
+ elements = Object.keys(a.elements)
+
+ for (var i = 0; i < elements.length; i++) {
+ var element = elements[i]
+ if (element in b.elements) {
+ intersection.push(element)
+ }
+ }
+
+ return new lunr.Set (intersection)
+}
+
+/**
+ * Returns a new set combining the elements of this and the specified set.
+ *
+ * @param {lunr.Set} other - set to union with this set.
+ * @return {lunr.Set} a new set that is the union of this and the specified set.
+ */
+
+lunr.Set.prototype.union = function (other) {
+ if (other === lunr.Set.complete) {
+ return lunr.Set.complete
+ }
+
+ if (other === lunr.Set.empty) {
+ return this
+ }
+
+ return new lunr.Set(Object.keys(this.elements).concat(Object.keys(other.elements)))
+}
+/**
+ * A function to calculate the inverse document frequency for
+ * a posting. This is shared between the builder and the index
+ *
+ * @private
+ * @param {object} posting - The posting for a given term
+ * @param {number} documentCount - The total number of documents.
+ */
+lunr.idf = function (posting, documentCount) {
+ var documentsWithTerm = 0
+
+ for (var fieldName in posting) {
+ if (fieldName == '_index') continue // Ignore the term index, its not a field
+ documentsWithTerm += Object.keys(posting[fieldName]).length
+ }
+
+ var x = (documentCount - documentsWithTerm + 0.5) / (documentsWithTerm + 0.5)
+
+ return Math.log(1 + Math.abs(x))
+}
+
+/**
+ * A token wraps a string representation of a token
+ * as it is passed through the text processing pipeline.
+ *
+ * @constructor
+ * @param {string} [str=''] - The string token being wrapped.
+ * @param {object} [metadata={}] - Metadata associated with this token.
+ */
+lunr.Token = function (str, metadata) {
+ this.str = str || ""
+ this.metadata = metadata || {}
+}
+
+/**
+ * Returns the token string that is being wrapped by this object.
+ *
+ * @returns {string}
+ */
+lunr.Token.prototype.toString = function () {
+ return this.str
+}
+
+/**
+ * A token update function is used when updating or optionally
+ * when cloning a token.
+ *
+ * @callback lunr.Token~updateFunction
+ * @param {string} str - The string representation of the token.
+ * @param {Object} metadata - All metadata associated with this token.
+ */
+
+/**
+ * Applies the given function to the wrapped string token.
+ *
+ * @example
+ * token.update(function (str, metadata) {
+ * return str.toUpperCase()
+ * })
+ *
+ * @param {lunr.Token~updateFunction} fn - A function to apply to the token string.
+ * @returns {lunr.Token}
+ */
+lunr.Token.prototype.update = function (fn) {
+ this.str = fn(this.str, this.metadata)
+ return this
+}
+
+/**
+ * Creates a clone of this token. Optionally a function can be
+ * applied to the cloned token.
+ *
+ * @param {lunr.Token~updateFunction} [fn] - An optional function to apply to the cloned token.
+ * @returns {lunr.Token}
+ */
+lunr.Token.prototype.clone = function (fn) {
+ fn = fn || function (s) { return s }
+ return new lunr.Token (fn(this.str, this.metadata), this.metadata)
+}
+/*!
+ * lunr.tokenizer
+ * Copyright (C) 2020 Oliver Nightingale
+ */
+
+/**
+ * A function for splitting a string into tokens ready to be inserted into
+ * the search index. Uses `lunr.tokenizer.separator` to split strings, change
+ * the value of this property to change how strings are split into tokens.
+ *
+ * This tokenizer will convert its parameter to a string by calling `toString` and
+ * then will split this string on the character in `lunr.tokenizer.separator`.
+ * Arrays will have their elements converted to strings and wrapped in a lunr.Token.
+ *
+ * Optional metadata can be passed to the tokenizer, this metadata will be cloned and
+ * added as metadata to every token that is created from the object to be tokenized.
+ *
+ * @static
+ * @param {?(string|object|object[])} obj - The object to convert into tokens
+ * @param {?object} metadata - Optional metadata to associate with every token
+ * @returns {lunr.Token[]}
+ * @see {@link lunr.Pipeline}
+ */
+lunr.tokenizer = function (obj, metadata) {
+ if (obj == null || obj == undefined) {
+ return []
+ }
+
+ if (Array.isArray(obj)) {
+ return obj.map(function (t) {
+ return new lunr.Token(
+ lunr.utils.asString(t).toLowerCase(),
+ lunr.utils.clone(metadata)
+ )
+ })
+ }
+
+ var str = obj.toString().toLowerCase(),
+ len = str.length,
+ tokens = []
+
+ for (var sliceEnd = 0, sliceStart = 0; sliceEnd <= len; sliceEnd++) {
+ var char = str.charAt(sliceEnd),
+ sliceLength = sliceEnd - sliceStart
+
+ if ((char.match(lunr.tokenizer.separator) || sliceEnd == len)) {
+
+ if (sliceLength > 0) {
+ var tokenMetadata = lunr.utils.clone(metadata) || {}
+ tokenMetadata["position"] = [sliceStart, sliceLength]
+ tokenMetadata["index"] = tokens.length
+
+ tokens.push(
+ new lunr.Token (
+ str.slice(sliceStart, sliceEnd),
+ tokenMetadata
+ )
+ )
+ }
+
+ sliceStart = sliceEnd + 1
+ }
+
+ }
+
+ return tokens
+}
+
+/**
+ * The separator used to split a string into tokens. Override this property to change the behaviour of
+ * `lunr.tokenizer` behaviour when tokenizing strings. By default this splits on whitespace and hyphens.
+ *
+ * @static
+ * @see lunr.tokenizer
+ */
+lunr.tokenizer.separator = /[\s\-]+/
+/*!
+ * lunr.Pipeline
+ * Copyright (C) 2020 Oliver Nightingale
+ */
+
+/**
+ * lunr.Pipelines maintain an ordered list of functions to be applied to all
+ * tokens in documents entering the search index and queries being ran against
+ * the index.
+ *
+ * An instance of lunr.Index created with the lunr shortcut will contain a
+ * pipeline with a stop word filter and an English language stemmer. Extra
+ * functions can be added before or after either of these functions or these
+ * default functions can be removed.
+ *
+ * When run the pipeline will call each function in turn, passing a token, the
+ * index of that token in the original list of all tokens and finally a list of
+ * all the original tokens.
+ *
+ * The output of functions in the pipeline will be passed to the next function
+ * in the pipeline. To exclude a token from entering the index the function
+ * should return undefined, the rest of the pipeline will not be called with
+ * this token.
+ *
+ * For serialisation of pipelines to work, all functions used in an instance of
+ * a pipeline should be registered with lunr.Pipeline. Registered functions can
+ * then be loaded. If trying to load a serialised pipeline that uses functions
+ * that are not registered an error will be thrown.
+ *
+ * If not planning on serialising the pipeline then registering pipeline functions
+ * is not necessary.
+ *
+ * @constructor
+ */
+lunr.Pipeline = function () {
+ this._stack = []
+}
+
+lunr.Pipeline.registeredFunctions = Object.create(null)
+
+/**
+ * A pipeline function maps lunr.Token to lunr.Token. A lunr.Token contains the token
+ * string as well as all known metadata. A pipeline function can mutate the token string
+ * or mutate (or add) metadata for a given token.
+ *
+ * A pipeline function can indicate that the passed token should be discarded by returning
+ * null, undefined or an empty string. This token will not be passed to any downstream pipeline
+ * functions and will not be added to the index.
+ *
+ * Multiple tokens can be returned by returning an array of tokens. Each token will be passed
+ * to any downstream pipeline functions and all will returned tokens will be added to the index.
+ *
+ * Any number of pipeline functions may be chained together using a lunr.Pipeline.
+ *
+ * @interface lunr.PipelineFunction
+ * @param {lunr.Token} token - A token from the document being processed.
+ * @param {number} i - The index of this token in the complete list of tokens for this document/field.
+ * @param {lunr.Token[]} tokens - All tokens for this document/field.
+ * @returns {(?lunr.Token|lunr.Token[])}
+ */
+
+/**
+ * Register a function with the pipeline.
+ *
+ * Functions that are used in the pipeline should be registered if the pipeline
+ * needs to be serialised, or a serialised pipeline needs to be loaded.
+ *
+ * Registering a function does not add it to a pipeline, functions must still be
+ * added to instances of the pipeline for them to be used when running a pipeline.
+ *
+ * @param {lunr.PipelineFunction} fn - The function to check for.
+ * @param {String} label - The label to register this function with
+ */
+lunr.Pipeline.registerFunction = function (fn, label) {
+ if (label in this.registeredFunctions) {
+ lunr.utils.warn('Overwriting existing registered function: ' + label)
+ }
+
+ fn.label = label
+ lunr.Pipeline.registeredFunctions[fn.label] = fn
+}
+
+/**
+ * Warns if the function is not registered as a Pipeline function.
+ *
+ * @param {lunr.PipelineFunction} fn - The function to check for.
+ * @private
+ */
+lunr.Pipeline.warnIfFunctionNotRegistered = function (fn) {
+ var isRegistered = fn.label && (fn.label in this.registeredFunctions)
+
+ if (!isRegistered) {
+ lunr.utils.warn('Function is not registered with pipeline. This may cause problems when serialising the index.\n', fn)
+ }
+}
+
+/**
+ * Loads a previously serialised pipeline.
+ *
+ * All functions to be loaded must already be registered with lunr.Pipeline.
+ * If any function from the serialised data has not been registered then an
+ * error will be thrown.
+ *
+ * @param {Object} serialised - The serialised pipeline to load.
+ * @returns {lunr.Pipeline}
+ */
+lunr.Pipeline.load = function (serialised) {
+ var pipeline = new lunr.Pipeline
+
+ serialised.forEach(function (fnName) {
+ var fn = lunr.Pipeline.registeredFunctions[fnName]
+
+ if (fn) {
+ pipeline.add(fn)
+ } else {
+ throw new Error('Cannot load unregistered function: ' + fnName)
+ }
+ })
+
+ return pipeline
+}
+
+/**
+ * Adds new functions to the end of the pipeline.
+ *
+ * Logs a warning if the function has not been registered.
+ *
+ * @param {lunr.PipelineFunction[]} functions - Any number of functions to add to the pipeline.
+ */
+lunr.Pipeline.prototype.add = function () {
+ var fns = Array.prototype.slice.call(arguments)
+
+ fns.forEach(function (fn) {
+ lunr.Pipeline.warnIfFunctionNotRegistered(fn)
+ this._stack.push(fn)
+ }, this)
+}
+
+/**
+ * Adds a single function after a function that already exists in the
+ * pipeline.
+ *
+ * Logs a warning if the function has not been registered.
+ *
+ * @param {lunr.PipelineFunction} existingFn - A function that already exists in the pipeline.
+ * @param {lunr.PipelineFunction} newFn - The new function to add to the pipeline.
+ */
+lunr.Pipeline.prototype.after = function (existingFn, newFn) {
+ lunr.Pipeline.warnIfFunctionNotRegistered(newFn)
+
+ var pos = this._stack.indexOf(existingFn)
+ if (pos == -1) {
+ throw new Error('Cannot find existingFn')
+ }
+
+ pos = pos + 1
+ this._stack.splice(pos, 0, newFn)
+}
+
+/**
+ * Adds a single function before a function that already exists in the
+ * pipeline.
+ *
+ * Logs a warning if the function has not been registered.
+ *
+ * @param {lunr.PipelineFunction} existingFn - A function that already exists in the pipeline.
+ * @param {lunr.PipelineFunction} newFn - The new function to add to the pipeline.
+ */
+lunr.Pipeline.prototype.before = function (existingFn, newFn) {
+ lunr.Pipeline.warnIfFunctionNotRegistered(newFn)
+
+ var pos = this._stack.indexOf(existingFn)
+ if (pos == -1) {
+ throw new Error('Cannot find existingFn')
+ }
+
+ this._stack.splice(pos, 0, newFn)
+}
+
+/**
+ * Removes a function from the pipeline.
+ *
+ * @param {lunr.PipelineFunction} fn The function to remove from the pipeline.
+ */
+lunr.Pipeline.prototype.remove = function (fn) {
+ var pos = this._stack.indexOf(fn)
+ if (pos == -1) {
+ return
+ }
+
+ this._stack.splice(pos, 1)
+}
+
+/**
+ * Runs the current list of functions that make up the pipeline against the
+ * passed tokens.
+ *
+ * @param {Array} tokens The tokens to run through the pipeline.
+ * @returns {Array}
+ */
+lunr.Pipeline.prototype.run = function (tokens) {
+ var stackLength = this._stack.length
+
+ for (var i = 0; i < stackLength; i++) {
+ var fn = this._stack[i]
+ var memo = []
+
+ for (var j = 0; j < tokens.length; j++) {
+ var result = fn(tokens[j], j, tokens)
+
+ if (result === null || result === void 0 || result === '') continue
+
+ if (Array.isArray(result)) {
+ for (var k = 0; k < result.length; k++) {
+ memo.push(result[k])
+ }
+ } else {
+ memo.push(result)
+ }
+ }
+
+ tokens = memo
+ }
+
+ return tokens
+}
+
+/**
+ * Convenience method for passing a string through a pipeline and getting
+ * strings out. This method takes care of wrapping the passed string in a
+ * token and mapping the resulting tokens back to strings.
+ *
+ * @param {string} str - The string to pass through the pipeline.
+ * @param {?object} metadata - Optional metadata to associate with the token
+ * passed to the pipeline.
+ * @returns {string[]}
+ */
+lunr.Pipeline.prototype.runString = function (str, metadata) {
+ var token = new lunr.Token (str, metadata)
+
+ return this.run([token]).map(function (t) {
+ return t.toString()
+ })
+}
+
+/**
+ * Resets the pipeline by removing any existing processors.
+ *
+ */
+lunr.Pipeline.prototype.reset = function () {
+ this._stack = []
+}
+
+/**
+ * Returns a representation of the pipeline ready for serialisation.
+ *
+ * Logs a warning if the function has not been registered.
+ *
+ * @returns {Array}
+ */
+lunr.Pipeline.prototype.toJSON = function () {
+ return this._stack.map(function (fn) {
+ lunr.Pipeline.warnIfFunctionNotRegistered(fn)
+
+ return fn.label
+ })
+}
+/*!
+ * lunr.Vector
+ * Copyright (C) 2020 Oliver Nightingale
+ */
+
+/**
+ * A vector is used to construct the vector space of documents and queries. These
+ * vectors support operations to determine the similarity between two documents or
+ * a document and a query.
+ *
+ * Normally no parameters are required for initializing a vector, but in the case of
+ * loading a previously dumped vector the raw elements can be provided to the constructor.
+ *
+ * For performance reasons vectors are implemented with a flat array, where an elements
+ * index is immediately followed by its value. E.g. [index, value, index, value]. This
+ * allows the underlying array to be as sparse as possible and still offer decent
+ * performance when being used for vector calculations.
+ *
+ * @constructor
+ * @param {Number[]} [elements] - The flat list of element index and element value pairs.
+ */
+lunr.Vector = function (elements) {
+ this._magnitude = 0
+ this.elements = elements || []
+}
+
+
+/**
+ * Calculates the position within the vector to insert a given index.
+ *
+ * This is used internally by insert and upsert. If there are duplicate indexes then
+ * the position is returned as if the value for that index were to be updated, but it
+ * is the callers responsibility to check whether there is a duplicate at that index
+ *
+ * @param {Number} insertIdx - The index at which the element should be inserted.
+ * @returns {Number}
+ */
+lunr.Vector.prototype.positionForIndex = function (index) {
+ // For an empty vector the tuple can be inserted at the beginning
+ if (this.elements.length == 0) {
+ return 0
+ }
+
+ var start = 0,
+ end = this.elements.length / 2,
+ sliceLength = end - start,
+ pivotPoint = Math.floor(sliceLength / 2),
+ pivotIndex = this.elements[pivotPoint * 2]
+
+ while (sliceLength > 1) {
+ if (pivotIndex < index) {
+ start = pivotPoint
+ }
+
+ if (pivotIndex > index) {
+ end = pivotPoint
+ }
+
+ if (pivotIndex == index) {
+ break
+ }
+
+ sliceLength = end - start
+ pivotPoint = start + Math.floor(sliceLength / 2)
+ pivotIndex = this.elements[pivotPoint * 2]
+ }
+
+ if (pivotIndex == index) {
+ return pivotPoint * 2
+ }
+
+ if (pivotIndex > index) {
+ return pivotPoint * 2
+ }
+
+ if (pivotIndex < index) {
+ return (pivotPoint + 1) * 2
+ }
+}
+
+/**
+ * Inserts an element at an index within the vector.
+ *
+ * Does not allow duplicates, will throw an error if there is already an entry
+ * for this index.
+ *
+ * @param {Number} insertIdx - The index at which the element should be inserted.
+ * @param {Number} val - The value to be inserted into the vector.
+ */
+lunr.Vector.prototype.insert = function (insertIdx, val) {
+ this.upsert(insertIdx, val, function () {
+ throw "duplicate index"
+ })
+}
+
+/**
+ * Inserts or updates an existing index within the vector.
+ *
+ * @param {Number} insertIdx - The index at which the element should be inserted.
+ * @param {Number} val - The value to be inserted into the vector.
+ * @param {function} fn - A function that is called for updates, the existing value and the
+ * requested value are passed as arguments
+ */
+lunr.Vector.prototype.upsert = function (insertIdx, val, fn) {
+ this._magnitude = 0
+ var position = this.positionForIndex(insertIdx)
+
+ if (this.elements[position] == insertIdx) {
+ this.elements[position + 1] = fn(this.elements[position + 1], val)
+ } else {
+ this.elements.splice(position, 0, insertIdx, val)
+ }
+}
+
+/**
+ * Calculates the magnitude of this vector.
+ *
+ * @returns {Number}
+ */
+lunr.Vector.prototype.magnitude = function () {
+ if (this._magnitude) return this._magnitude
+
+ var sumOfSquares = 0,
+ elementsLength = this.elements.length
+
+ for (var i = 1; i < elementsLength; i += 2) {
+ var val = this.elements[i]
+ sumOfSquares += val * val
+ }
+
+ return this._magnitude = Math.sqrt(sumOfSquares)
+}
+
+/**
+ * Calculates the dot product of this vector and another vector.
+ *
+ * @param {lunr.Vector} otherVector - The vector to compute the dot product with.
+ * @returns {Number}
+ */
+lunr.Vector.prototype.dot = function (otherVector) {
+ var dotProduct = 0,
+ a = this.elements, b = otherVector.elements,
+ aLen = a.length, bLen = b.length,
+ aVal = 0, bVal = 0,
+ i = 0, j = 0
+
+ while (i < aLen && j < bLen) {
+ aVal = a[i], bVal = b[j]
+ if (aVal < bVal) {
+ i += 2
+ } else if (aVal > bVal) {
+ j += 2
+ } else if (aVal == bVal) {
+ dotProduct += a[i + 1] * b[j + 1]
+ i += 2
+ j += 2
+ }
+ }
+
+ return dotProduct
+}
+
+/**
+ * Calculates the similarity between this vector and another vector.
+ *
+ * @param {lunr.Vector} otherVector - The other vector to calculate the
+ * similarity with.
+ * @returns {Number}
+ */
+lunr.Vector.prototype.similarity = function (otherVector) {
+ return this.dot(otherVector) / this.magnitude() || 0
+}
+
+/**
+ * Converts the vector to an array of the elements within the vector.
+ *
+ * @returns {Number[]}
+ */
+lunr.Vector.prototype.toArray = function () {
+ var output = new Array (this.elements.length / 2)
+
+ for (var i = 1, j = 0; i < this.elements.length; i += 2, j++) {
+ output[j] = this.elements[i]
+ }
+
+ return output
+}
+
+/**
+ * A JSON serializable representation of the vector.
+ *
+ * @returns {Number[]}
+ */
+lunr.Vector.prototype.toJSON = function () {
+ return this.elements
+}
+/* eslint-disable */
+/*!
+ * lunr.stemmer
+ * Copyright (C) 2020 Oliver Nightingale
+ * Includes code from - http://tartarus.org/~martin/PorterStemmer/js.txt
+ */
+
+/**
+ * lunr.stemmer is an english language stemmer, this is a JavaScript
+ * implementation of the PorterStemmer taken from http://tartarus.org/~martin
+ *
+ * @static
+ * @implements {lunr.PipelineFunction}
+ * @param {lunr.Token} token - The string to stem
+ * @returns {lunr.Token}
+ * @see {@link lunr.Pipeline}
+ * @function
+ */
+lunr.stemmer = (function(){
+ var step2list = {
+ "ational" : "ate",
+ "tional" : "tion",
+ "enci" : "ence",
+ "anci" : "ance",
+ "izer" : "ize",
+ "bli" : "ble",
+ "alli" : "al",
+ "entli" : "ent",
+ "eli" : "e",
+ "ousli" : "ous",
+ "ization" : "ize",
+ "ation" : "ate",
+ "ator" : "ate",
+ "alism" : "al",
+ "iveness" : "ive",
+ "fulness" : "ful",
+ "ousness" : "ous",
+ "aliti" : "al",
+ "iviti" : "ive",
+ "biliti" : "ble",
+ "logi" : "log"
+ },
+
+ step3list = {
+ "icate" : "ic",
+ "ative" : "",
+ "alize" : "al",
+ "iciti" : "ic",
+ "ical" : "ic",
+ "ful" : "",
+ "ness" : ""
+ },
+
+ c = "[^aeiou]", // consonant
+ v = "[aeiouy]", // vowel
+ C = c + "[^aeiouy]*", // consonant sequence
+ V = v + "[aeiou]*", // vowel sequence
+
+ mgr0 = "^(" + C + ")?" + V + C, // [C]VC... is m>0
+ meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$", // [C]VC[V] is m=1
+ mgr1 = "^(" + C + ")?" + V + C + V + C, // [C]VCVC... is m>1
+ s_v = "^(" + C + ")?" + v; // vowel in stem
+
+ var re_mgr0 = new RegExp(mgr0);
+ var re_mgr1 = new RegExp(mgr1);
+ var re_meq1 = new RegExp(meq1);
+ var re_s_v = new RegExp(s_v);
+
+ var re_1a = /^(.+?)(ss|i)es$/;
+ var re2_1a = /^(.+?)([^s])s$/;
+ var re_1b = /^(.+?)eed$/;
+ var re2_1b = /^(.+?)(ed|ing)$/;
+ var re_1b_2 = /.$/;
+ var re2_1b_2 = /(at|bl|iz)$/;
+ var re3_1b_2 = new RegExp("([^aeiouylsz])\\1$");
+ var re4_1b_2 = new RegExp("^" + C + v + "[^aeiouwxy]$");
+
+ var re_1c = /^(.+?[^aeiou])y$/;
+ var re_2 = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/;
+
+ var re_3 = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/;
+
+ var re_4 = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/;
+ var re2_4 = /^(.+?)(s|t)(ion)$/;
+
+ var re_5 = /^(.+?)e$/;
+ var re_5_1 = /ll$/;
+ var re3_5 = new RegExp("^" + C + v + "[^aeiouwxy]$");
+
+ var porterStemmer = function porterStemmer(w) {
+ var stem,
+ suffix,
+ firstch,
+ re,
+ re2,
+ re3,
+ re4;
+
+ if (w.length < 3) { return w; }
+
+ firstch = w.substr(0,1);
+ if (firstch == "y") {
+ w = firstch.toUpperCase() + w.substr(1);
+ }
+
+ // Step 1a
+ re = re_1a
+ re2 = re2_1a;
+
+ if (re.test(w)) { w = w.replace(re,"$1$2"); }
+ else if (re2.test(w)) { w = w.replace(re2,"$1$2"); }
+
+ // Step 1b
+ re = re_1b;
+ re2 = re2_1b;
+ if (re.test(w)) {
+ var fp = re.exec(w);
+ re = re_mgr0;
+ if (re.test(fp[1])) {
+ re = re_1b_2;
+ w = w.replace(re,"");
+ }
+ } else if (re2.test(w)) {
+ var fp = re2.exec(w);
+ stem = fp[1];
+ re2 = re_s_v;
+ if (re2.test(stem)) {
+ w = stem;
+ re2 = re2_1b_2;
+ re3 = re3_1b_2;
+ re4 = re4_1b_2;
+ if (re2.test(w)) { w = w + "e"; }
+ else if (re3.test(w)) { re = re_1b_2; w = w.replace(re,""); }
+ else if (re4.test(w)) { w = w + "e"; }
+ }
+ }
+
+ // Step 1c - replace suffix y or Y by i if preceded by a non-vowel which is not the first letter of the word (so cry -> cri, by -> by, say -> say)
+ re = re_1c;
+ if (re.test(w)) {
+ var fp = re.exec(w);
+ stem = fp[1];
+ w = stem + "i";
+ }
+
+ // Step 2
+ re = re_2;
+ if (re.test(w)) {
+ var fp = re.exec(w);
+ stem = fp[1];
+ suffix = fp[2];
+ re = re_mgr0;
+ if (re.test(stem)) {
+ w = stem + step2list[suffix];
+ }
+ }
+
+ // Step 3
+ re = re_3;
+ if (re.test(w)) {
+ var fp = re.exec(w);
+ stem = fp[1];
+ suffix = fp[2];
+ re = re_mgr0;
+ if (re.test(stem)) {
+ w = stem + step3list[suffix];
+ }
+ }
+
+ // Step 4
+ re = re_4;
+ re2 = re2_4;
+ if (re.test(w)) {
+ var fp = re.exec(w);
+ stem = fp[1];
+ re = re_mgr1;
+ if (re.test(stem)) {
+ w = stem;
+ }
+ } else if (re2.test(w)) {
+ var fp = re2.exec(w);
+ stem = fp[1] + fp[2];
+ re2 = re_mgr1;
+ if (re2.test(stem)) {
+ w = stem;
+ }
+ }
+
+ // Step 5
+ re = re_5;
+ if (re.test(w)) {
+ var fp = re.exec(w);
+ stem = fp[1];
+ re = re_mgr1;
+ re2 = re_meq1;
+ re3 = re3_5;
+ if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) {
+ w = stem;
+ }
+ }
+
+ re = re_5_1;
+ re2 = re_mgr1;
+ if (re.test(w) && re2.test(w)) {
+ re = re_1b_2;
+ w = w.replace(re,"");
+ }
+
+ // and turn initial Y back to y
+
+ if (firstch == "y") {
+ w = firstch.toLowerCase() + w.substr(1);
+ }
+
+ return w;
+ };
+
+ return function (token) {
+ return token.update(porterStemmer);
+ }
+})();
+
+lunr.Pipeline.registerFunction(lunr.stemmer, 'stemmer')
+/*!
+ * lunr.stopWordFilter
+ * Copyright (C) 2020 Oliver Nightingale
+ */
+
+/**
+ * lunr.generateStopWordFilter builds a stopWordFilter function from the provided
+ * list of stop words.
+ *
+ * The built in lunr.stopWordFilter is built using this generator and can be used
+ * to generate custom stopWordFilters for applications or non English languages.
+ *
+ * @function
+ * @param {Array} token The token to pass through the filter
+ * @returns {lunr.PipelineFunction}
+ * @see lunr.Pipeline
+ * @see lunr.stopWordFilter
+ */
+lunr.generateStopWordFilter = function (stopWords) {
+ var words = stopWords.reduce(function (memo, stopWord) {
+ memo[stopWord] = stopWord
+ return memo
+ }, {})
+
+ return function (token) {
+ if (token && words[token.toString()] !== token.toString()) return token
+ }
+}
+
+/**
+ * lunr.stopWordFilter is an English language stop word list filter, any words
+ * contained in the list will not be passed through the filter.
+ *
+ * This is intended to be used in the Pipeline. If the token does not pass the
+ * filter then undefined will be returned.
+ *
+ * @function
+ * @implements {lunr.PipelineFunction}
+ * @params {lunr.Token} token - A token to check for being a stop word.
+ * @returns {lunr.Token}
+ * @see {@link lunr.Pipeline}
+ */
+lunr.stopWordFilter = lunr.generateStopWordFilter([
+ 'a',
+ 'able',
+ 'about',
+ 'across',
+ 'after',
+ 'all',
+ 'almost',
+ 'also',
+ 'am',
+ 'among',
+ 'an',
+ 'and',
+ 'any',
+ 'are',
+ 'as',
+ 'at',
+ 'be',
+ 'because',
+ 'been',
+ 'but',
+ 'by',
+ 'can',
+ 'cannot',
+ 'could',
+ 'dear',
+ 'did',
+ 'do',
+ 'does',
+ 'either',
+ 'else',
+ 'ever',
+ 'every',
+ 'for',
+ 'from',
+ 'get',
+ 'got',
+ 'had',
+ 'has',
+ 'have',
+ 'he',
+ 'her',
+ 'hers',
+ 'him',
+ 'his',
+ 'how',
+ 'however',
+ 'i',
+ 'if',
+ 'in',
+ 'into',
+ 'is',
+ 'it',
+ 'its',
+ 'just',
+ 'least',
+ 'let',
+ 'like',
+ 'likely',
+ 'may',
+ 'me',
+ 'might',
+ 'most',
+ 'must',
+ 'my',
+ 'neither',
+ 'no',
+ 'nor',
+ 'not',
+ 'of',
+ 'off',
+ 'often',
+ 'on',
+ 'only',
+ 'or',
+ 'other',
+ 'our',
+ 'own',
+ 'rather',
+ 'said',
+ 'say',
+ 'says',
+ 'she',
+ 'should',
+ 'since',
+ 'so',
+ 'some',
+ 'than',
+ 'that',
+ 'the',
+ 'their',
+ 'them',
+ 'then',
+ 'there',
+ 'these',
+ 'they',
+ 'this',
+ 'tis',
+ 'to',
+ 'too',
+ 'twas',
+ 'us',
+ 'wants',
+ 'was',
+ 'we',
+ 'were',
+ 'what',
+ 'when',
+ 'where',
+ 'which',
+ 'while',
+ 'who',
+ 'whom',
+ 'why',
+ 'will',
+ 'with',
+ 'would',
+ 'yet',
+ 'you',
+ 'your'
+])
+
+lunr.Pipeline.registerFunction(lunr.stopWordFilter, 'stopWordFilter')
+/*!
+ * lunr.trimmer
+ * Copyright (C) 2020 Oliver Nightingale
+ */
+
+/**
+ * lunr.trimmer is a pipeline function for trimming non word
+ * characters from the beginning and end of tokens before they
+ * enter the index.
+ *
+ * This implementation may not work correctly for non latin
+ * characters and should either be removed or adapted for use
+ * with languages with non-latin characters.
+ *
+ * @static
+ * @implements {lunr.PipelineFunction}
+ * @param {lunr.Token} token The token to pass through the filter
+ * @returns {lunr.Token}
+ * @see lunr.Pipeline
+ */
+lunr.trimmer = function (token) {
+ return token.update(function (s) {
+ return s.replace(/^\W+/, '').replace(/\W+$/, '')
+ })
+}
+
+lunr.Pipeline.registerFunction(lunr.trimmer, 'trimmer')
+/*!
+ * lunr.TokenSet
+ * Copyright (C) 2020 Oliver Nightingale
+ */
+
+/**
+ * A token set is used to store the unique list of all tokens
+ * within an index. Token sets are also used to represent an
+ * incoming query to the index, this query token set and index
+ * token set are then intersected to find which tokens to look
+ * up in the inverted index.
+ *
+ * A token set can hold multiple tokens, as in the case of the
+ * index token set, or it can hold a single token as in the
+ * case of a simple query token set.
+ *
+ * Additionally token sets are used to perform wildcard matching.
+ * Leading, contained and trailing wildcards are supported, and
+ * from this edit distance matching can also be provided.
+ *
+ * Token sets are implemented as a minimal finite state automata,
+ * where both common prefixes and suffixes are shared between tokens.
+ * This helps to reduce the space used for storing the token set.
+ *
+ * @constructor
+ */
+lunr.TokenSet = function () {
+ this.final = false
+ this.edges = {}
+ this.id = lunr.TokenSet._nextId
+ lunr.TokenSet._nextId += 1
+}
+
+/**
+ * Keeps track of the next, auto increment, identifier to assign
+ * to a new tokenSet.
+ *
+ * TokenSets require a unique identifier to be correctly minimised.
+ *
+ * @private
+ */
+lunr.TokenSet._nextId = 1
+
+/**
+ * Creates a TokenSet instance from the given sorted array of words.
+ *
+ * @param {String[]} arr - A sorted array of strings to create the set from.
+ * @returns {lunr.TokenSet}
+ * @throws Will throw an error if the input array is not sorted.
+ */
+lunr.TokenSet.fromArray = function (arr) {
+ var builder = new lunr.TokenSet.Builder
+
+ for (var i = 0, len = arr.length; i < len; i++) {
+ builder.insert(arr[i])
+ }
+
+ builder.finish()
+ return builder.root
+}
+
+/**
+ * Creates a token set from a query clause.
+ *
+ * @private
+ * @param {Object} clause - A single clause from lunr.Query.
+ * @param {string} clause.term - The query clause term.
+ * @param {number} [clause.editDistance] - The optional edit distance for the term.
+ * @returns {lunr.TokenSet}
+ */
+lunr.TokenSet.fromClause = function (clause) {
+ if ('editDistance' in clause) {
+ return lunr.TokenSet.fromFuzzyString(clause.term, clause.editDistance)
+ } else {
+ return lunr.TokenSet.fromString(clause.term)
+ }
+}
+
+/**
+ * Creates a token set representing a single string with a specified
+ * edit distance.
+ *
+ * Insertions, deletions, substitutions and transpositions are each
+ * treated as an edit distance of 1.
+ *
+ * Increasing the allowed edit distance will have a dramatic impact
+ * on the performance of both creating and intersecting these TokenSets.
+ * It is advised to keep the edit distance less than 3.
+ *
+ * @param {string} str - The string to create the token set from.
+ * @param {number} editDistance - The allowed edit distance to match.
+ * @returns {lunr.Vector}
+ */
+lunr.TokenSet.fromFuzzyString = function (str, editDistance) {
+ var root = new lunr.TokenSet
+
+ var stack = [{
+ node: root,
+ editsRemaining: editDistance,
+ str: str
+ }]
+
+ while (stack.length) {
+ var frame = stack.pop()
+
+ // no edit
+ if (frame.str.length > 0) {
+ var char = frame.str.charAt(0),
+ noEditNode
+
+ if (char in frame.node.edges) {
+ noEditNode = frame.node.edges[char]
+ } else {
+ noEditNode = new lunr.TokenSet
+ frame.node.edges[char] = noEditNode
+ }
+
+ if (frame.str.length == 1) {
+ noEditNode.final = true
+ }
+
+ stack.push({
+ node: noEditNode,
+ editsRemaining: frame.editsRemaining,
+ str: frame.str.slice(1)
+ })
+ }
+
+ if (frame.editsRemaining == 0) {
+ continue
+ }
+
+ // insertion
+ if ("*" in frame.node.edges) {
+ var insertionNode = frame.node.edges["*"]
+ } else {
+ var insertionNode = new lunr.TokenSet
+ frame.node.edges["*"] = insertionNode
+ }
+
+ if (frame.str.length == 0) {
+ insertionNode.final = true
+ }
+
+ stack.push({
+ node: insertionNode,
+ editsRemaining: frame.editsRemaining - 1,
+ str: frame.str
+ })
+
+ // deletion
+ // can only do a deletion if we have enough edits remaining
+ // and if there are characters left to delete in the string
+ if (frame.str.length > 1) {
+ stack.push({
+ node: frame.node,
+ editsRemaining: frame.editsRemaining - 1,
+ str: frame.str.slice(1)
+ })
+ }
+
+ // deletion
+ // just removing the last character from the str
+ if (frame.str.length == 1) {
+ frame.node.final = true
+ }
+
+ // substitution
+ // can only do a substitution if we have enough edits remaining
+ // and if there are characters left to substitute
+ if (frame.str.length >= 1) {
+ if ("*" in frame.node.edges) {
+ var substitutionNode = frame.node.edges["*"]
+ } else {
+ var substitutionNode = new lunr.TokenSet
+ frame.node.edges["*"] = substitutionNode
+ }
+
+ if (frame.str.length == 1) {
+ substitutionNode.final = true
+ }
+
+ stack.push({
+ node: substitutionNode,
+ editsRemaining: frame.editsRemaining - 1,
+ str: frame.str.slice(1)
+ })
+ }
+
+ // transposition
+ // can only do a transposition if there are edits remaining
+ // and there are enough characters to transpose
+ if (frame.str.length > 1) {
+ var charA = frame.str.charAt(0),
+ charB = frame.str.charAt(1),
+ transposeNode
+
+ if (charB in frame.node.edges) {
+ transposeNode = frame.node.edges[charB]
+ } else {
+ transposeNode = new lunr.TokenSet
+ frame.node.edges[charB] = transposeNode
+ }
+
+ if (frame.str.length == 1) {
+ transposeNode.final = true
+ }
+
+ stack.push({
+ node: transposeNode,
+ editsRemaining: frame.editsRemaining - 1,
+ str: charA + frame.str.slice(2)
+ })
+ }
+ }
+
+ return root
+}
+
+/**
+ * Creates a TokenSet from a string.
+ *
+ * The string may contain one or more wildcard characters (*)
+ * that will allow wildcard matching when intersecting with
+ * another TokenSet.
+ *
+ * @param {string} str - The string to create a TokenSet from.
+ * @returns {lunr.TokenSet}
+ */
+lunr.TokenSet.fromString = function (str) {
+ var node = new lunr.TokenSet,
+ root = node
+
+ /*
+ * Iterates through all characters within the passed string
+ * appending a node for each character.
+ *
+ * When a wildcard character is found then a self
+ * referencing edge is introduced to continually match
+ * any number of any characters.
+ */
+ for (var i = 0, len = str.length; i < len; i++) {
+ var char = str[i],
+ final = (i == len - 1)
+
+ if (char == "*") {
+ node.edges[char] = node
+ node.final = final
+
+ } else {
+ var next = new lunr.TokenSet
+ next.final = final
+
+ node.edges[char] = next
+ node = next
+ }
+ }
+
+ return root
+}
+
+/**
+ * Converts this TokenSet into an array of strings
+ * contained within the TokenSet.
+ *
+ * This is not intended to be used on a TokenSet that
+ * contains wildcards, in these cases the results are
+ * undefined and are likely to cause an infinite loop.
+ *
+ * @returns {string[]}
+ */
+lunr.TokenSet.prototype.toArray = function () {
+ var words = []
+
+ var stack = [{
+ prefix: "",
+ node: this
+ }]
+
+ while (stack.length) {
+ var frame = stack.pop(),
+ edges = Object.keys(frame.node.edges),
+ len = edges.length
+
+ if (frame.node.final) {
+ /* In Safari, at this point the prefix is sometimes corrupted, see:
+ * https://github.com/olivernn/lunr.js/issues/279 Calling any
+ * String.prototype method forces Safari to "cast" this string to what
+ * it's supposed to be, fixing the bug. */
+ frame.prefix.charAt(0)
+ words.push(frame.prefix)
+ }
+
+ for (var i = 0; i < len; i++) {
+ var edge = edges[i]
+
+ stack.push({
+ prefix: frame.prefix.concat(edge),
+ node: frame.node.edges[edge]
+ })
+ }
+ }
+
+ return words
+}
+
+/**
+ * Generates a string representation of a TokenSet.
+ *
+ * This is intended to allow TokenSets to be used as keys
+ * in objects, largely to aid the construction and minimisation
+ * of a TokenSet. As such it is not designed to be a human
+ * friendly representation of the TokenSet.
+ *
+ * @returns {string}
+ */
+lunr.TokenSet.prototype.toString = function () {
+ // NOTE: Using Object.keys here as this.edges is very likely
+ // to enter 'hash-mode' with many keys being added
+ //
+ // avoiding a for-in loop here as it leads to the function
+ // being de-optimised (at least in V8). From some simple
+ // benchmarks the performance is comparable, but allowing
+ // V8 to optimize may mean easy performance wins in the future.
+
+ if (this._str) {
+ return this._str
+ }
+
+ var str = this.final ? '1' : '0',
+ labels = Object.keys(this.edges).sort(),
+ len = labels.length
+
+ for (var i = 0; i < len; i++) {
+ var label = labels[i],
+ node = this.edges[label]
+
+ str = str + label + node.id
+ }
+
+ return str
+}
+
+/**
+ * Returns a new TokenSet that is the intersection of
+ * this TokenSet and the passed TokenSet.
+ *
+ * This intersection will take into account any wildcards
+ * contained within the TokenSet.
+ *
+ * @param {lunr.TokenSet} b - An other TokenSet to intersect with.
+ * @returns {lunr.TokenSet}
+ */
+lunr.TokenSet.prototype.intersect = function (b) {
+ var output = new lunr.TokenSet,
+ frame = undefined
+
+ var stack = [{
+ qNode: b,
+ output: output,
+ node: this
+ }]
+
+ while (stack.length) {
+ frame = stack.pop()
+
+ // NOTE: As with the #toString method, we are using
+ // Object.keys and a for loop instead of a for-in loop
+ // as both of these objects enter 'hash' mode, causing
+ // the function to be de-optimised in V8
+ var qEdges = Object.keys(frame.qNode.edges),
+ qLen = qEdges.length,
+ nEdges = Object.keys(frame.node.edges),
+ nLen = nEdges.length
+
+ for (var q = 0; q < qLen; q++) {
+ var qEdge = qEdges[q]
+
+ for (var n = 0; n < nLen; n++) {
+ var nEdge = nEdges[n]
+
+ if (nEdge == qEdge || qEdge == '*') {
+ var node = frame.node.edges[nEdge],
+ qNode = frame.qNode.edges[qEdge],
+ final = node.final && qNode.final,
+ next = undefined
+
+ if (nEdge in frame.output.edges) {
+ // an edge already exists for this character
+ // no need to create a new node, just set the finality
+ // bit unless this node is already final
+ next = frame.output.edges[nEdge]
+ next.final = next.final || final
+
+ } else {
+ // no edge exists yet, must create one
+ // set the finality bit and insert it
+ // into the output
+ next = new lunr.TokenSet
+ next.final = final
+ frame.output.edges[nEdge] = next
+ }
+
+ stack.push({
+ qNode: qNode,
+ output: next,
+ node: node
+ })
+ }
+ }
+ }
+ }
+
+ return output
+}
+lunr.TokenSet.Builder = function () {
+ this.previousWord = ""
+ this.root = new lunr.TokenSet
+ this.uncheckedNodes = []
+ this.minimizedNodes = {}
+}
+
+lunr.TokenSet.Builder.prototype.insert = function (word) {
+ var node,
+ commonPrefix = 0
+
+ if (word < this.previousWord) {
+ throw new Error ("Out of order word insertion")
+ }
+
+ for (var i = 0; i < word.length && i < this.previousWord.length; i++) {
+ if (word[i] != this.previousWord[i]) break
+ commonPrefix++
+ }
+
+ this.minimize(commonPrefix)
+
+ if (this.uncheckedNodes.length == 0) {
+ node = this.root
+ } else {
+ node = this.uncheckedNodes[this.uncheckedNodes.length - 1].child
+ }
+
+ for (var i = commonPrefix; i < word.length; i++) {
+ var nextNode = new lunr.TokenSet,
+ char = word[i]
+
+ node.edges[char] = nextNode
+
+ this.uncheckedNodes.push({
+ parent: node,
+ char: char,
+ child: nextNode
+ })
+
+ node = nextNode
+ }
+
+ node.final = true
+ this.previousWord = word
+}
+
+lunr.TokenSet.Builder.prototype.finish = function () {
+ this.minimize(0)
+}
+
+lunr.TokenSet.Builder.prototype.minimize = function (downTo) {
+ for (var i = this.uncheckedNodes.length - 1; i >= downTo; i--) {
+ var node = this.uncheckedNodes[i],
+ childKey = node.child.toString()
+
+ if (childKey in this.minimizedNodes) {
+ node.parent.edges[node.char] = this.minimizedNodes[childKey]
+ } else {
+ // Cache the key for this node since
+ // we know it can't change anymore
+ node.child._str = childKey
+
+ this.minimizedNodes[childKey] = node.child
+ }
+
+ this.uncheckedNodes.pop()
+ }
+}
+/*!
+ * lunr.Index
+ * Copyright (C) 2020 Oliver Nightingale
+ */
+
+/**
+ * An index contains the built index of all documents and provides a query interface
+ * to the index.
+ *
+ * Usually instances of lunr.Index will not be created using this constructor, instead
+ * lunr.Builder should be used to construct new indexes, or lunr.Index.load should be
+ * used to load previously built and serialized indexes.
+ *
+ * @constructor
+ * @param {Object} attrs - The attributes of the built search index.
+ * @param {Object} attrs.invertedIndex - An index of term/field to document reference.
+ * @param {Object' + noResultsText + '
'); + } +} + +function doSearch () { + var query = document.getElementById('mkdocs-search-query').value; + if (query.length > min_search_length) { + if (!window.Worker) { + displayResults(search(query)); + } else { + searchWorker.postMessage({query: query}); + } + } else { + // Clear results for short queries + displayResults([]); + } +} + +function initSearch () { + var search_input = document.getElementById('mkdocs-search-query'); + if (search_input) { + search_input.addEventListener("keyup", doSearch); + } + var term = getSearchTermFromLocation(); + if (term) { + search_input.value = term; + doSearch(); + } +} + +function onWorkerMessage (e) { + if (e.data.allowSearch) { + initSearch(); + } else if (e.data.results) { + var results = e.data.results; + displayResults(results); + } else if (e.data.config) { + min_search_length = e.data.config.min_search_length-1; + } +} + +if (!window.Worker) { + console.log('Web Worker API not supported'); + // load index in main thread + $.getScript(joinUrl(base_url, "search/worker.js")).done(function () { + console.log('Loaded worker'); + init(); + window.postMessage = function (msg) { + onWorkerMessage({data: msg}); + }; + }).fail(function (jqxhr, settings, exception) { + console.error('Could not load worker.js'); + }); +} else { + // Wrap search in a web worker + var searchWorker = new Worker(joinUrl(base_url, "search/worker.js")); + searchWorker.postMessage({init: true}); + searchWorker.onmessage = onWorkerMessage; +} diff --git a/search/search_index.json b/search/search_index.json new file mode 100644 index 0000000..c039673 --- /dev/null +++ b/search/search_index.json @@ -0,0 +1 @@ +{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Introduction to MicroTBX-Modbus MicroTBX-Modbus is a modern Modbus communication stack, targeting microcontroller based embedded systems. Its aim is to be: easy to use, easy to port, high quality, well maintained, stable and flexible. The ideal solution for any embedded software engineer, with an interest in adding Modbus communication to their product. Features Carefully crafted application programming interface ( API ), focusing on ease of use. Written in the C programming language (C99) with high MISRA compliance . Supports both Modbus client and Modbus server functionality. Supports multi channel for both the Modbus client and server. Flexible dual licensing model. Designed such that it can be used with and without and RTOS. Easy to integrate into existing software projects, especially when using CMake. Includes C++ wrappers for those preferring to develop in an object-oriented manner. Quick and simple to adjust to your microcontroller system. No compile-time configuration needed. Option to implement additional and custom Modbus function codes. Supported function codes MicroTBX-Modbus currently supports the following Modbus function codes: Function Code Name 1 Read Coils 2 Read Discrete Inputs 3 Read Holding Registers 4 Read Input Registers 5 Write Single Coil 6 Write Single Register 8 Diagnostics (sub codes: 0, 10, 11, 12, 13, 14, 15) 15 Write Multiple Coils 16 Write Multiple Registers Note that MicroTBX-Modbus includes functionality, enabling you to extend it by adding support for additional and custom function codes. Why another Modbus stack? With Modbus being such a convenient and mature communication protocol, several other Modbus software stacks exist; Both closed sourced and open sourced. Why bother with developing and maintaining yet another one? It turns out that most of the existing ones all seem to be limiting on at least one front: No multi-channel support. Not including both client and server functionality. Not being able to add support for additional and custom function codes. Skipping features needed for protocol compliance. No open source option. Not actively maintained. MicroTBX-Modbus addresses all these limitations. Thanks to the flexible dual licensing model, you can start out right away with the open source GPLv3 version. Perfect for testing, evaluation and prototyping purposes. Once you're satisfied with it and would like to include MicroTBX-Modbus in your proprietary closed sourced product, you can move on to the commercial license. The only reason not to use MicroTBX-Modbus is that it currently only supports Modbus RTU communication. Note though that support for ASCII and TCP communication is planned for the future. System requirements With MicroTBX-Modbus being a modern communication stack, the focus is more on ease and flexibility of use for the developer, and less on keeping the ROM footprint low. Therefore the recommended system requirements are slightly higher than comparative Modbus software solutions: It is recommended to use a microcontroller with at least 32 KiB flash and 4 KiB RAM. However, it will run on a basic 8-bit microcontroller with just 10 KiB of flash and 1.5 KiB RAM. Although you then run out of storage space quickly, when adding your own firmware\u2019s functionality. Next steps The getting started section of this user manual shows you how to quickly setup a Modbus server and client. Definitely worth a glance if you're new to MicroTBX-Modbus. For those who want to see MicroTBX-Modbus in action, you can find ready-to-run demo programs located in a separate repository. These demo programs target an ever growing collection of popular microcontroller evaluation boards and serve as a good starting point: https://github.com/feaser/microtbx-demos If you're ready to integrate MicroTBX-Modbus into your own embedded software project, head over to the integration section of this user manual for detailed instructions. MicroTBX-Modbus itself is hardware independent. To handle the hardware specifics of your microcontroller, you just need to implement a few port functions. A template source-file is provided. You can find detailed instructions in the portation section of this user manual. Once you got everything up-and-running and would like to use MicroTBX-Modbus in the closed source proprietary firmware of your product, make sure to upgrade to the commercial license . The default GPLv3 licensed version is not suitable for that use case.","title":"Home"},{"location":"#introduction-to-microtbx-modbus","text":"MicroTBX-Modbus is a modern Modbus communication stack, targeting microcontroller based embedded systems. Its aim is to be: easy to use, easy to port, high quality, well maintained, stable and flexible. The ideal solution for any embedded software engineer, with an interest in adding Modbus communication to their product.","title":"Introduction to MicroTBX-Modbus"},{"location":"#features","text":"Carefully crafted application programming interface ( API ), focusing on ease of use. Written in the C programming language (C99) with high MISRA compliance . Supports both Modbus client and Modbus server functionality. Supports multi channel for both the Modbus client and server. Flexible dual licensing model. Designed such that it can be used with and without and RTOS. Easy to integrate into existing software projects, especially when using CMake. Includes C++ wrappers for those preferring to develop in an object-oriented manner. Quick and simple to adjust to your microcontroller system. No compile-time configuration needed. Option to implement additional and custom Modbus function codes.","title":"Features"},{"location":"#supported-function-codes","text":"MicroTBX-Modbus currently supports the following Modbus function codes: Function Code Name 1 Read Coils 2 Read Discrete Inputs 3 Read Holding Registers 4 Read Input Registers 5 Write Single Coil 6 Write Single Register 8 Diagnostics (sub codes: 0, 10, 11, 12, 13, 14, 15) 15 Write Multiple Coils 16 Write Multiple Registers Note that MicroTBX-Modbus includes functionality, enabling you to extend it by adding support for additional and custom function codes.","title":"Supported function codes"},{"location":"#why-another-modbus-stack","text":"With Modbus being such a convenient and mature communication protocol, several other Modbus software stacks exist; Both closed sourced and open sourced. Why bother with developing and maintaining yet another one? It turns out that most of the existing ones all seem to be limiting on at least one front: No multi-channel support. Not including both client and server functionality. Not being able to add support for additional and custom function codes. Skipping features needed for protocol compliance. No open source option. Not actively maintained. MicroTBX-Modbus addresses all these limitations. Thanks to the flexible dual licensing model, you can start out right away with the open source GPLv3 version. Perfect for testing, evaluation and prototyping purposes. Once you're satisfied with it and would like to include MicroTBX-Modbus in your proprietary closed sourced product, you can move on to the commercial license. The only reason not to use MicroTBX-Modbus is that it currently only supports Modbus RTU communication. Note though that support for ASCII and TCP communication is planned for the future.","title":"Why another Modbus stack?"},{"location":"#system-requirements","text":"With MicroTBX-Modbus being a modern communication stack, the focus is more on ease and flexibility of use for the developer, and less on keeping the ROM footprint low. Therefore the recommended system requirements are slightly higher than comparative Modbus software solutions: It is recommended to use a microcontroller with at least 32 KiB flash and 4 KiB RAM. However, it will run on a basic 8-bit microcontroller with just 10 KiB of flash and 1.5 KiB RAM. Although you then run out of storage space quickly, when adding your own firmware\u2019s functionality.","title":"System requirements"},{"location":"#next-steps","text":"The getting started section of this user manual shows you how to quickly setup a Modbus server and client. Definitely worth a glance if you're new to MicroTBX-Modbus. For those who want to see MicroTBX-Modbus in action, you can find ready-to-run demo programs located in a separate repository. These demo programs target an ever growing collection of popular microcontroller evaluation boards and serve as a good starting point: https://github.com/feaser/microtbx-demos If you're ready to integrate MicroTBX-Modbus into your own embedded software project, head over to the integration section of this user manual for detailed instructions. MicroTBX-Modbus itself is hardware independent. To handle the hardware specifics of your microcontroller, you just need to implement a few port functions. A template source-file is provided. You can find detailed instructions in the portation section of this user manual. Once you got everything up-and-running and would like to use MicroTBX-Modbus in the closed source proprietary firmware of your product, make sure to upgrade to the commercial license . The default GPLv3 licensed version is not suitable for that use case.","title":"Next steps"},{"location":"apiref/","text":"API reference This section provides a full reference of all the functions, macros and types that MicroTBX-Modbus offers. Macros Version Macro Description TBX_MB_VERSION_MAIN Main version number of MicroTBX-Modbus. TBX_MB_VERSION_MINOR Minor version number of MicroTBX-Modbus. TBX_MB_VERSION_PATCH Patch number of MicroTBX-Modbus. Common Function codes. Macro Description TBX_MB_FC01_READ_COILS Modbus function code 01 - Read Coils. TBX_MB_FC02_READ_DISCRETE_INPUTS Modbus function code 02 - Read Discrete Inputs. TBX_MB_FC03_READ_HOLDING_REGISTERS Modbus function code 03 - Read Holding Registers. TBX_MB_FC04_READ_INPUT_REGISTERS Modbus function code 04 - Read Input Registers. TBX_MB_FC05_WRITE_SINGLE_COIL Modbus function code 05 - Write Single Coil. TBX_MB_FC06_WRITE_SINGLE_REGISTER Modbus function code 06 - Write Single Register. TBX_MB_FC08_DIAGNOSTICS Modbus function code 08 - Diagnostics. TBX_MB_FC15_WRITE_MULTIPLE_COILS Modbus function code 15 - Write Multiple Coils. TBX_MB_FC16_WRITE_MULTIPLE_REGISTERS Modbus function code 16 - Write Multiple Registers. Exception codes. Macro Description TBX_MB_EC01_ILLEGAL_FUNCTION Modbus exception code 01 - Illegal function. TBX_MB_EC02_ILLEGAL_DATA_ADDRESS Modbus exception code 02 - Illegal data address. TBX_MB_EC03_ILLEGAL_DATA_VALUE Modbus exception code 03 - Illegal data value. TBX_MB_EC04_SERVER_DEVICE_FAILURE Modbus exception code 04 - Server device failure. Diagnostics sub function codes. Macro Description TBX_MB_DIAG_SC_QUERY_DATA Diagnostics sub-function code - Return Query Data. TBX_MB_DIAG_SC_CLEAR_COUNTERS Diagnostics sub-function code - Clear Counters. TBX_MB_DIAG_SC_BUS_MESSAGE_COUNT Diagnostics sub-function code - Return Bus Message Count. TBX_MB_DIAG_SC_BUS_COMM_ERROR_COUNT Diagnostics sub-function code - Return Bus Communication Error Count. TBX_MB_DIAG_SC_BUS_EXCEPTION_ERROR_COUNT Diagnostics sub-function code - Return Bus Exception Error Count. TBX_MB_DIAG_SC_SERVER_MESSAGE_COUNT Diagnostics sub-function code - Return Server Message Count. TBX_MB_DIAG_SC_SERVER_NO_RESPONSE_COUNT Diagnostics sub-function code - Return Server No Response Count. Miscellaneous. Macro Description TBX_MB_FC_EXCEPTION_MASK Bit mask to OR to the function code to flag it as an exception response. Transport layer Node address. Macro Description TBX_MB_TP_NODE_ADDR_BROADCAST Node address value for broadcast purposes. TBX_MB_TP_NODE_ADDR_MIN Minimum value of a valid node address. TBX_MB_TP_NODE_ADDR_MAX Maximum value of a valid node address. Protocol data unit (PDU). Macro Description TBX_MB_TP_PDU_CODE_LEN_MAX Maximum size of the \"Function code\" at the start of a PDU. TBX_MB_TP_PDU_DATA_LEN_MAX Maximum number of data bytes inside a PDU. This excludes the function code. TBX_MB_TP_PDU_MAX_LEN Maximum length of a PDU. Types Server tTbxMbServer typedef void * tTbxMbServer Handle to a Modbus server channel object, in the format of an opaque pointer. tTbxMbServerResult typedef enum { TBX_MB_SERVER_OK = 0U, TBX_MB_SERVER_ERR_ILLEGAL_DATA_ADDR, TBX_MB_SERVER_ERR_DEVICE_FAILURE } tTbxMbServerResult numerated type with all supported return values for the callbacks. tTbxMbServerReadInput typedef tTbxMbServerResult (* tTbxMbServerReadInput)(tTbxMbServer channel, uint16_t addr, uint8_t * value) Modbus server callback function for reading a discrete input. Parameter Description channel Handle to the Modbus server channel object that triggered the callback. addr Element address ( 0 .. 65535 ). value Pointer to write the value of the input to. Use TBX_ON if the input is on, TBX_OFF otherwise. Return value TBX_MB_SERVER_OK if successful, TBX_MB_SERVER_ERR_ILLEGAL_DATA_ADDR if the specific data element address is not supported by this server, TBX_MB_SERVER_ERR_DEVICE_FAILURE otherwise. tTbxMbServerReadCoil typedef tTbxMbServerResult (* tTbxMbServerReadCoil)(tTbxMbServer channel, uint16_t addr, uint8_t * value) Modbus server callback function for reading a coil. Parameter Description channel Handle to the Modbus server channel object that triggered the callback. addr Element address ( 0 .. 65535 ). value Pointer to write the value of the coil to. Use TBX_ON if the coils is on, TBX_OFF otherwise. Return value TBX_MB_SERVER_OK if successful, TBX_MB_SERVER_ERR_ILLEGAL_DATA_ADDR if the specific data element address is not supported by this server, TBX_MB_SERVER_ERR_DEVICE_FAILURE otherwise. tTbxMbServerWriteCoil typedef tTbxMbServerResult (* tTbxMbServerWriteCoil)(tTbxMbServer channel, uint16_t addr, uint8_t value) Modbus server callback function for writing a coil. Parameter Description channel Handle to the Modbus server channel object that triggered the callback. addr Element address ( 0 .. 65535 ). value Coil value. Use TBX_ON to activate the coil, TBX_OFF otherwise. Return value TBX_MB_SERVER_OK if successful, TBX_MB_SERVER_ERR_ILLEGAL_DATA_ADDR if the specific data element address is not supported by this server, TBX_MB_SERVER_ERR_DEVICE_FAILURE otherwise. tTbxMbServerReadInputReg typedef tTbxMbServerResult (* tTbxMbServerReadInputReg)(tTbxMbServer channel, uint16_t addr, uint16_t * value) Modbus server callback function for reading an input register. Parameter Description channel Handle to the Modbus server channel object that triggered the callback. addr Element address ( 0 .. 65535 ). value Pointer to write the value of the input register to. Return value TBX_MB_SERVER_OK if successful, TBX_MB_SERVER_ERR_ILLEGAL_DATA_ADDR if the specific data element address is not supported by this server, TBX_MB_SERVER_ERR_DEVICE_FAILURE otherwise. tTbxMbServerReadHoldingReg typedef tTbxMbServerResult (* tTbxMbServerReadHoldingReg)(tTbxMbServer channel, uint16_t addr, uint16_t * value) Modbus server callback function for reading a holding register. Parameter Description channel Handle to the Modbus server channel object that triggered the callback. addr Element address ( 0 .. 65535 ). value Pointer to write the value of the holding register to. Return value TBX_MB_SERVER_OK if successful, TBX_MB_SERVER_ERR_ILLEGAL_DATA_ADDR if the specific data element address is not supported by this server, TBX_MB_SERVER_ERR_DEVICE_FAILURE otherwise. tTbxMbServerWriteHoldingReg typedef tTbxMbServerResult (* tTbxMbServerWriteHoldingReg)(tTbxMbServer channel, uint16_t addr, uint16_t value) Modbus server callback function for writing a holding register. Parameter Description channel Handle to the Modbus server channel object that triggered the callback. addr Element address ( 0 .. 65535 ). value Value of the holding register. Return value TBX_MB_SERVER_OK if successful, TBX_MB_SERVER_ERR_ILLEGAL_DATA_ADDR if the specific data element address is not supported by this server, TBX_MB_SERVER_ERR_DEVICE_FAILURE otherwise. tTbxMbServerCustomFunction typedef uint8_t (* tTbxMbServerCustomFunction)(tTbxMbServer channel, uint8_t const * rxPdu, uint8_t * txPdu, uint8_t * len) Modbus server callback function for implementing custom function code handling. Thanks to this functionality, the user can support Modbus function codes that are either currently not supported or user defined extensions. The rxPdu and txPdu parameters are pointers to the byte array of the PDU. The first byte (i.e. rxPdu[0] ) contains the function code, followed by its data bytes. Upon calling the callback, the len parameter contains the length of rxPdu . When preparing the response, you can write the length of the txPdu response to len as well. Parameter Description channel Handle to the Modbus server channel object that triggered the callback. rxPdu Pointer to a byte array for reading the received PDU. txPdu Pointer to a byte array for writing the response PDU. len Pointer to the PDU length, including the function code. Return value TBX_TRUE if the callback function handled the received function code and prepared a response PDU. TBX_FALSE otherwise. Client tTbxMbClient typedef void * tTbxMbClient Handle to a Modbus client channel object, in the format of an opaque pointer. Transport layer tTbxMbTp typedef void * tTbxMbTp Handle to a Modbus transport layer object, in the format of an opaque pointer. UART tTbxMbUartPort typedef enum { TBX_MB_UART_PORT1 = 0U, TBX_MB_UART_PORT2, TBX_MB_UART_PORT3, TBX_MB_UART_PORT4, TBX_MB_UART_PORT5, TBX_MB_UART_PORT6, TBX_MB_UART_PORT7, TBX_MB_UART_PORT8, TBX_MB_UART_NUM_PORT } tTbxMbUartPort Enumerated type with all supported UART ports. tTbxMbUartBaudrate typedef enum { TBX_MB_UART_1200BPS = 0U, TBX_MB_UART_2400BPS, TBX_MB_UART_4800BPS, TBX_MB_UART_9600BPS, TBX_MB_UART_19200BPS, TBX_MB_UART_38400BPS, TBX_MB_UART_57600BPS, TBX_MB_UART_115200BPS, TBX_MB_UART_NUM_BAUDRATE } tTbxMbUartBaudrate Enumerated type with all supported UART baudrates. tTbxMbUartDatabits typedef enum { TBX_MB_UART_7_DATABITS = 0U, TBX_MB_UART_8_DATABITS, TBX_MB_UART_NUM_DATABITS } tTbxMbUartDatabits Enumerated type with all supported UART data bits modes. tTbxMbUartStopbits typedef enum { TBX_MB_UART_1_STOPBITS = 0U, TBX_MB_UART_2_STOPBITS, TBX_MB_UART_NUM_STOPBITS } tTbxMbUartStopbits Enumerated type with all supported parity modes. tTbxMbUartParity typedef enum { TBX_MB_ODD_PARITY = 0U, TBX_MB_EVEN_PARITY, TBX_MB_NO_PARITY, TBX_MB_UART_NUM_PARITY } tTbxMbUartParity Enumerated type with all supported parity modes. Functions Server TbxMbServerCreate tTbxMbServer TbxMbServerCreate(tTbxMbTp transport) Creates a Modbus server channel object and assigns the specified Modbus transport layer to the channel for packet transmission and reception. This example creates a Modbus RTU server channel object for a node with address 10 : /* Construct a Modbus RTU transport layer object. */ tTbxMbTp modbusTp = TbxMbRtuCreate(10U, TBX_MB_UART_PORT1, TBX_MB_UART_19200BPS, TBX_MB_UART_1_STOPBITS, TBX_MB_EVEN_PARITY); /* Construct a Modbus server object. */ tTbxMbServer modbusServer = TbxMbServerCreate(modbusTp); Parameter Description transport Handle to a previously created Modbus transport layer object to assign to the channel. Return value Handle to the newly created Modbus server channel object if successful, NULL otherwise. TbxMbServerFree void TbxMbServerFree(tTbxMbServer channel) Releases a Modbus server channel object, previously created with TbxMbServerCreate() . Parameter Description channel Handle to the Modbus server channel object to release. TbxMbServerSetCallbackReadInput void TbxMbServerSetCallbackReadInput(tTbxMbServer channel, tTbxMbServerReadInput callback) Registers the callback function that this server calls, whenever a client requests the reading of a specific discrete input. The example connects the state of two digital inputs to the Modbus discrete inputs at addresses 10000 to 10001 : tTbxMbServerResult AppReadInput(tTbxMbServer channel, uint16_t addr, uint8_t * value) { tTbxMbServerResult result = TBX_MB_SERVER_OK; /* Filter on the requested discrete input address. */ switch (addr) { case 10000U: *value = BspDigitalIn(BSP_DIGITAL_IN1); break; case 10001U: *value = BspDigitalIn(BSP_DIGITAL_IN2); break; default: /* Unsupported discrete input address. */ result = TBX_MB_SERVER_ERR_ILLEGAL_DATA_ADDR; break; } /* Give the result back to the caller. */ return result; } /* Set the callback for reading the Modbus discrete inputs. */ TbxMbServerSetCallbackReadInput(modbusServer, AppReadInput); Parameter Description channel Handle to the Modbus server channel object. callback Pointer to the callback function. TbxMbServerSetCallbackReadCoil void TbxMbServerSetCallbackReadCoil(tTbxMbServer channel, tTbxMbServerReadCoil callback) Registers the callback function that this server calls, whenever a client requests the reading of a specific coil. The example assumes the application stores the state of two coils in an array with name appCoils[] . Whenever a client requests the reading of the Modbus coils at addresses 0 to 1 , the currently stored values in the appCoils[] array are returned: uint8_t appCoils[2] = { TBX_ON, TBX_OFF }; tTbxMbServerResult AppReadCoil(tTbxMbServer channel, uint16_t addr, uint8_t * value) { tTbxMbServerResult result = TBX_MB_SERVER_ERR_ILLEGAL_DATA_ADDR; /* Supported coil address? */ if (addr <= 1U) { /* Store the current coil state. */ *value = appCoils[addr]; result = TBX_MB_SERVER_OK; } /* Give the result back to the caller. */ return result; } /* Set the callback for reading the Modbus coils. */ TbxMbServerSetCallbackReadCoil(modbusServer, AppReadCoil); Parameter Description channel Handle to the Modbus server channel object. callback Pointer to the callback function. TbxMbServerSetCallbackWriteCoil void TbxMbServerSetCallbackWriteCoil(tTbxMbServer channel, tTbxMbServerWriteCoil callback) Registers the callback function that this server calls, whenever a client requests the writing of a specific coil. The example connects the Modbus coil addresses 0 to 1 to the state of two digital outputs: tTbxMbServerResult AppWriteCoil(tTbxMbServer channel, uint16_t addr, uint8_t value) { tTbxMbServerResult result = TBX_MB_SERVER_OK; /* Filter on the requested coil address. */ switch (addr) { case 0U: BspDigitalOut(BSP_DIGITAL_OUT1, value); break; case 1U: BspDigitalOut(BSP_DIGITAL_OUT2, value); break; default: /* Unsupported coil address. */ result = TBX_MB_SERVER_ERR_ILLEGAL_DATA_ADDR; break; } /* Give the result back to the caller. */ return result; } /* Set the callback for writing the Modbus coils. */ TbxMbServerSetCallbackWriteCoil(modbusServer, AppWriteCoil); Parameter Description channel Handle to the Modbus server channel object. callback Pointer to the callback function. TbxMbServerSetCallbackReadInputReg void TbxMbServerSetCallbackReadInputReg(tTbxMbServer channel, tTbxMbServerReadInputReg callback) Registers the callback function that this server calls, whenever a client requests the reading of a specific input register. The example connects the state of two analog inputs to the Modbus input registers at addresses 30000 to 30001 : tTbxMbServerResult AppReadInputReg(tTbxMbServer channel, uint16_t addr, uint16_t * value) { tTbxMbServerResult result = TBX_MB_SERVER_OK; /* Filter on the requested input register address. */ switch (addr) { case 30000U: *value = BspAnalogIn(BSP_ANALOG_IN1); break; case 30001U: *value = BspAnalogIn(BSP_ANALOG_IN2); break; default: /* Unsupported input register address. */ result = TBX_MB_SERVER_ERR_ILLEGAL_DATA_ADDR; break; } /* Give the result back to the caller. */ return result; } /* Set the callback for reading the Modbus input registers. */ TbxMbServerSetCallbackReadInputReg(modbusServer, AppReadInputReg); Parameter Description channel Handle to the Modbus server channel object. callback Pointer to the callback function. TbxMbServerSetCallbackReadHoldingReg void TbxMbServerSetCallbackReadHoldingReg(tTbxMbServer channel, tTbxMbServerReadHoldingReg callback) Registers the callback function that this server calls, whenever a client requests the reading of a specific holding register. The example assumes the application stores the state of two holding registers in an array with name appHoldingRegs[] . Whenever a client requests the reading of the Modbus holding registers at addresses 40000 to 40001 , the currently stored values in the appHoldingRegs[] array are returned: uint16_t appHoldingRegs[2] = { 1234, 5678 }; tTbxMbServerResult AppReadHoldingReg(tTbxMbServer channel, uint16_t addr, uint16_t * value) { tTbxMbServerResult result = TBX_MB_SERVER_ERR_ILLEGAL_DATA_ADDR; /* Supported holding register address? */ if ( (addr >= 40000) && (addr <= 40001U) ) { /* Store the holding register state. */ *value = appHoldingReg[addr - 40000U]; result = TBX_MB_SERVER_OK; } /* Give the result back to the caller. */ return result; } /* Set the callback for reading the Modbus holding registers. */ TbxMbServerSetCallbackReadHoldingReg(modbusServer, AppReadHoldingReg); Parameter Description channel Handle to the Modbus server channel object. callback Pointer to the callback function. TbxMbServerSetCallbackWriteHoldingReg void TbxMbServerSetCallbackWriteHoldingReg(tTbxMbServer channel, tTbxMbServerWriteHoldingReg callback) Registers the callback function that this server calls, whenever a client requests the writing of a specific holding register. The example connects the Modbus holding registers addresses 40000 to 40001 to two 8-bit PWM output signals: tTbxMbServerResult AppWriteHoldingReg(tTbxMbServer channel, uint16_t addr, uint16_t value) { tTbxMbServerResult result = TBX_MB_SERVER_OK; /* Filter on the requested holding register address. */ switch (addr) { case 40000U: /* PWM supports 8-bit duty cycle. */ if (value <= 255U) { BspPwmOut(BSP_PWM_OUT1, (uint8_t)value); } else { result = TBX_MB_SERVER_ERR_DEVICE_FAILURE; } break; case 40001U: /* PWM supports 8-bit duty cycle. */ if (value <= 255U) { BspPwmOut(BSP_PWM_OUT2, (uint8_t)value); } else { result = TBX_MB_SERVER_ERR_DEVICE_FAILURE; } break; default: /* Unsupported holding register address. */ result = TBX_MB_SERVER_ERR_ILLEGAL_DATA_ADDR; break; } /* Give the result back to the caller. */ return result; } /* Set the callback for writing the Modbus holding registers. */ TbxMbServerSetCallbackWriteHoldingReg(modbusServer, AppWriteHoldingReg); Parameter Description channel Handle to the Modbus server channel object. callback Pointer to the callback function. TbxMbServerSetCallbackCustomFunction void TbxMbServerSetCallbackCustomFunction (tTbxMbServer channel, tTbxMbServerCustomFunction callback) Registers the callback function that this server calls, whenever it received a PDU containing a function code not currently supported. With the aid of this callback function the user can implement support for new function codes. The example shows how to add support for function code 17 ( Report Server ID ). It's the counter-part to the example for TbxMbClientCustomFunction() . According to the Modbus protocol, the response to the Report Server ID request is device specific. The device implementation decides the number of bytes for the Server ID and if additional data is added to the response. The following code snippet implements support for Report Server ID , where the actual server ID is 16-bits and the response contains no additional data: uint8_t AppReportServerIdCallback(tTbxMbServer channel, uint8_t const * rxPdu, uint8_t * txPdu, uint8_t * len) { uint8_t result = TBX_FALSE; /* Function code 17 - Report Server ID? */ if (rxPdu[0] == 17U) { /* Check the expected request length. */ if (*len == 1U) { /* Prepare the response. */ txPdu[0] = 17U; /* Function code. */ txPdu[1] = 3U; /* Byte count. */ TbxMbCommonStoreUInt16BE(0x1234U, &txPdu[2]); /* server ID. */ txPdu[4] = 0xFFU; /* Run indicator status = ON. */ *len = 5U; /* Function code handled. */ result = TBX_TRUE; } } /* Give the result back to the caller. */ return result; } /* Set the callback for handling custom function codes. */ TbxMbServerSetCallbackCustomFunction(modbusServer, AppReportServerIdCallback); Parameter Description channel Handle to the Modbus server channel object. callback Pointer to the callback function. Client TbxMbClientCreate tTbxMbClient TbxMbClientCreate(tTbxMbTp transport, uint16_t responseTimeout, uint16_t turnaroundDelay) Creates a Modbus client channel object and assigns the specified Modbus transport layer to the channel for packet transmission and reception. This example creates a Modbus RTU client channel object. Note the the nodeAddr parameter of function TbxMbRtuCreate() is not applicable when used on a client and should simply be set to a value of 0 : /* Construct a Modbus RTU transport layer object. */ tTbxMbTp modbusTp = TbxMbRtuCreate(0U, TBX_MB_UART_PORT1, TBX_MB_UART_19200BPS, TBX_MB_UART_1_STOPBITS, TBX_MB_EVEN_PARITY); /* Construct a Modbus client object. */ tTbxMbClient modbusClient = TbxMbClientCreate(modbusTp, 1000U, 100U); Parameter Description transport Handle to a previously created Modbus transport layer object to assign to the channel. responseTimeout Maximum time in milliseconds to wait for a response from the Modbus server, after sending a PDU. turnaroundDelay Delay time in milliseconds after sending a broadcast PDU to give all recipients sufficient time to process the PDU. Return value Handle to the newly created Modbus client channel object if successful, NULL otherwise. TbxMbClientFree void TbxMbClientFree(tTbxMbClient channel) Releases a Modbus client channel object, previously created with TbxMbClientCreate() . Parameter Description channel Handle to the Modbus client channel object to release. TbxMbClientReadCoils uint8_t TbxMbClientReadCoils(tTbxMbClient channel, uint8_t node, uint16_t addr, uint16_t num, uint8_t * coils) Reads the coil(s) from the server with the specified node address. The example reads the state of two coils at Modbus addresses 0 to 1 , from a Modbus server with node address 10 : uint8_t coils[2] = { 0 }; TbxMbClientReadCoils(modbusClient, 10U, 0U, 2U, coils); Parameter Description channel Handle to the Modbus client channel for the requested operation. node The address of the server. This parameter is transport layer dependent. It is needed on RTU/ASCII, yet don't care for TCP unless it is a gateway to an RTU network. If it's don't care, set it to a value of 1 . addr Starting element address (0..65535) in the Modbus data table for the coil read operation. num Number of elements to read from the coils data table. Range can be 1 .. 2000 . coils Pointer to array with TBX_ON / TBX_OFF values where the coil state will be written to. Return value TBX_OK if successful, TBX_ERROR otherwise. TbxMbClientReadInputs uint8_t TbxMbClientReadInputs(tTbxMbClient channel, uint8_t node, uint16_t addr, uint16_t num, uint8_t * inputs) Reads the discrete input(s) from the server with the specified node address. The example reads the state of two discrete inputs at Modbus addresses 10000 to 10001 , from a Modbus server with node address 10 : uint8_t inputs[2] = { 0 }; TbxMbClientReadInputs(modbusClient, 10U, 10000U, 2U, inputs); Parameter Description channel Handle to the Modbus client channel for the requested operation. node The address of the server. This parameter is transport layer dependent. It is needed on RTU/ASCII, yet don't care for TCP unless it is a gateway to an RTU network. If it's don't care, set it to a value of 1 . addr Starting element address (0..65535) in the Modbus data table for the discrete input read operation. num Number of elements to read from the discrete inputs data table. Range can be 1 .. 2000 . inputs Pointer to array with TBX_ON / TBX_OFF values where the discrete input state will be written to. Return value TBX_OK if successful, TBX_ERROR otherwise. TbxMbClientReadInputRegs uint8_t TbxMbClientReadInputRegs(tTbxMbClient channel, uint8_t node, uint16_t addr, uint8_t num, uint16_t * inputRegs) Reads the input register(s) from the server with the specified node address. The example reads two input registers at Modbus addresses 30000 to 30001 , from a Modbus server with node address 10 : uint16_t inputRegs[2] = { 0 }; TbxMbClientReadInputRegs(modbusClient, 10U, 30000U, 2U, inputRegs); Parameter Description channel Handle to the Modbus client channel for the requested operation. node The address of the server. This parameter is transport layer dependent. It is needed on RTU/ASCII, yet don't care for TCP unless it is a gateway to an RTU network. If it's don't care, set it to a value of 1 . addr Starting element address (0..65535) in the Modbus data table for the input register read operation. num Number of elements to read from the input registers data table. Range can be 1 .. 125 . inputRegs Pointer to array where the input register values will be written to. Return value TBX_OK if successful, TBX_ERROR otherwise. TbxMbClientReadHoldingRegs uint8_t TbxMbClientReadHoldingRegs(tTbxMbClient channel, uint8_t node, uint16_t addr, uint8_t num, uint16_t * holdingRegs) Reads the holding register(s) from the server with the specified node address. The example reads two holding registers at Modbus addresses 40000 to 40001 , from a Modbus server with node address 10 : uint16_t holdingRegs[2] = { 0 }; TbxMbClientReadHoldingRegs(modbusClient, 10U, 40000U, 2U, holdingRegs); Parameter Description channel Handle to the Modbus client channel for the requested operation. node The address of the server. This parameter is transport layer dependent. It is needed on RTU/ASCII, yet don't care for TCP unless it is a gateway to an RTU network. If it's don't care, set it to a value of 1 . addr Starting element address (0..65535) in the Modbus data table for the holding register read operation. num Number of elements to read from the holding registers data table. Range can be 1 .. 125 . holdingRegs Pointer to array where the holding register values will be written to. Return value TBX_OK if successful, TBX_ERROR otherwise. TbxMbClientWriteCoils uint8_t TbxMbClientWriteCoils(tTbxMbClient channel, uint8_t node, uint16_t addr, uint16_t num, uint8_t const * coils) Writes the coil(s) to the server with the specified node address. The example writes the state of two coils at Modbus addresses 0 to 1 , to a Modbus server with node address 10 : uint8_t coils[2] = { TBX_OFF, TBX_OFF }; TbxMbClientWriteCoils(modbusClient, 10U, 0U, 2U, coils); Parameter Description channel Handle to the Modbus client channel for the requested operation. node The address of the server. This parameter is transport layer dependent. It is needed on RTU/ASCII, yet don't care for TCP unless it is a gateway to an RTU network. If it's don't care, set it to a value of 1 . addr Starting element address (0..65535) in the Modbus data table for the coil write operation. num Number of elements to write to the coils data table. Range can be 1 .. 1968 . coils Pointer to array with the desired TBX_ON / TBX_OFF coil values. Return value TBX_OK if successful, TBX_ERROR otherwise. TbxMbClientWriteHoldingRegs uint8_t TbxMbClientWriteHoldingRegs(tTbxMbClient channel, uint8_t node, uint16_t addr, uint8_t num, uint16_t const * holdingRegs) Writes the holding register(s) to the server with the specified node address. The example writes two holding registers at Modbus addresses 40000 to 40001 , to a Modbus server with node address 10 : uint16_t holdingRegs[2] = { 63U, 127U }; TbxMbClientWriteHoldingRegs(modbusClient, 10U, 40000U, 2U, holdingRegs); Parameter Description channel Handle to the Modbus client channel for the requested operation. node The address of the server. This parameter is transport layer dependent. It is needed on RTU/ASCII, yet don't care for TCP unless it is a gateway to an RTU network. If it's don't care, set it to a value of 1 . addr Starting element address (0..65535) in the Modbus data table for the holding register write operation. num Number of elements to write to the holding registers data table. Range can be 1 .. 123 . holdingRegs Pointer to array with the desired holding register values. Return value TBX_OK if successful, TBX_ERROR otherwise. TbxMbClientDiagnostics uint8_t TbxMbClientDiagnostics(tTbxMbClient channel, uint8_t node, uint16_t subcode, uint16_t * count) Perform diagnostic operation on the server for checking the communication system. The example obtains the number of packets with a correct CRC, received by a Modbus server with node address 10 : uint16_t count = 0U; TbxMbClientDiagnostics(modbusClient, 10U, TBX_MB_DIAG_SC_SERVER_MESSAGE_COUNT, &count); Parameter Description channel Handle to the Modbus client channel for the requested operation. node The address of the server. This parameter is transport layer dependent. It is needed on RTU/ASCII, yet don't care for TCP unless it is a gateway to an RTU network. If it's don't care, set it to a value of 1 . subcode Sub-function code for specifying the diagnostic operation to perform. Currently supported values: - TBX_MB_DIAG_SC_QUERY_DATA - TBX_MB_DIAG_SC_CLEAR_COUNTERS - TBX_MB_DIAG_SC_BUS_MESSAGE_COUNT - TBX_MB_DIAG_SC_BUS_COMM_ERROR_COUNT - TBX_MB_DIAG_SC_BUS_EXCEPTION_ERROR_COUNT - TBX_MB_DIAG_SC_SERVER_MESSAGE_COUNT - TBX_MB_DIAG_SC_SERVER_NO_RESPONSE_COUNT count Location where the retrieved count value will be written to. Only applicable for the sub-function codes that end with _COUNT . Return value TBX_OK if successful, TBX_ERROR otherwise. TbxMbClientCustomFunction uint8_t TbxMbClientCustomFunction(tTbxMbClient channel, uint8_t node, uint8_t const * txPdu, uint8_t * rxPdu, uint8_t * len) Send a custom function code PDU to the server and receive its response PDU. Thanks to this functionality, the user can support Modbus function codes that are either currently not supported or user defined extensions. The txPdu and rxPdu parameters are pointers to the byte array of the PDU. The first byte (i.e. txPdu[0] ) contains the function code, followed by its data bytes. When calling this function, set the len parameter to the length of the txPdu . This function updates the len parameter with the length of the received PDU, which it stores in rxPdu . The example shows how to add support for function code 17 ( Report Server ID ). It's the counter-part to the example for TbxMbServerSetCallbackCustomFunction() . According to the Modbus protocol, the response to the Report Server ID request is device specific. The device implementation decides the number of bytes for the Server ID and if additional data is added to the response. The following code snippet implements support for Report Server ID , where it reads out the 16-bit server ID of a Modbus server with node address 10 : uint16_t AppReportServerId(tTbxMbClient channel, uint8_t node) { /* static to lower stack load. */ static uint8_t response[TBX_MB_TP_PDU_MAX_LEN]; uint8_t request[1] = { 17U }; uint8_t len = 1U; uint16_t result = 0U; /* Transceive function code 17 - Report Server ID. */ if (TbxMbClientCustomFunction(channel, node, request, response, &len) == TBX_OK) { /* Response length as expected? */ if (len == 5U) { /* Not an exception response and byte count correct? */ if ((response[0] == 17U) && (response[1] == 3U)) { /* Read out the received server ID. */ result = TbxMbCommonExtractUInt16BE(&response[2]); } } } /* Give the result back to the caller. */ return result; } /* Read the server ID. */ uint16_t serverId = AppReportServerId(modbusClient, 10U); Parameter Description channel Handle to the Modbus client channel for the requested operation. node The address of the server. This parameter is transport layer dependent. It is needed on RTU/ASCII, yet don't care for TCP unless it is a gateway to an RTU network. If it's don't care, set it to a value of 1 . txPdu Pointer to a byte array with the PDU to transmit. rxPdu Pointer to a byte array with the received response PDU. len Pointer to the PDU length, including the function code. Return value TBX_OK if successful, TBX_ERROR otherwise. Event TbxMbEventTask void TbxMbEventTask(void) Task function that drives the entire Modbus stack. It processes internally generated events. How to call this function depends on the selected operating system abstraction layer (OSAL), which you determine based on the source/osal/tbxmb_XXX.c source file you compile and link with your firmware. In a traditional superloop application ( tbxmb_superloop.c ), call this function continuously in the infinite program loop: #include