diff --git a/.editorconfig b/.editorconfig index c346a38..b43926b 100644 --- a/.editorconfig +++ b/.editorconfig @@ -96,3 +96,9 @@ max_line_length = 75 [Kconfig*] indent_style = tab indent_size = 8 + +# Markdown +[*.md] +indent_style = space +indent_size = 2 +max_line_length = 72 diff --git a/README.md b/README.md new file mode 100644 index 0000000..2613c18 --- /dev/null +++ b/README.md @@ -0,0 +1,336 @@ +# Golioth Modbus Reference Design + +The Modbus Reference Design demonstrates how to interface with a +[Banner Sure Cross® +QM30VT2](https://www.bannerengineering.com/us/en/products/part.806276.html) +sensor via the Modbus protocol and send vibration and temperature +measurements to the cloud using the Golioth IoT platform. + +Sensor values are uploaded to the cloud and stored in Golioth's LightDB +Stream database. The sensor sampling frequency and other sensor +parameters are remotely configurable via the Golioth Settings service. + +Business use cases and hardware build details are available on [the +Modbus Vibration Monitor Project +Page](https://projects.golioth.io/reference-designs/modbus-vibration-monitor/). + +This repository contains the firmware source code and [pre-built release +firmware +images](https://github.com/golioth/reference-design-modbus-vibration-monitor/releases). + +## Supported Hardware + +- Nordic nRF9160-DK +- Golioth Aludel Elixir +- Golioth Aludel Mini + +### Additional Sensors/Components + +- Texas Instruments THVD1426 RS-485 transceiver + +## Golioth Features + +This app implements: + + - [Device Settings + Service](https://docs.golioth.io/firmware/golioth-firmware-sdk/device-settings-service) + - [Remote Procedure Call + (RPC)](https://docs.golioth.io/firmware/golioth-firmware-sdk/remote-procedure-call) + - [Stream + Client](https://docs.golioth.io/firmware/golioth-firmware-sdk/stream-client) + - [LightDB State + Client](https://docs.golioth.io/firmware/golioth-firmware-sdk/light-db-state/) + - [Over-the-Air (OTA) Firmware + Upgrade](https://docs.golioth.io/firmware/golioth-firmware-sdk/firmware-upgrade/firmware-upgrade) + - [Backend + Logging](https://docs.golioth.io/device-management/logging/) + +### Settings Service + +The following settings should be set in the Device Settings menu of the +[Golioth Console](https://console.golioth.io). + + - `LOOP_DELAY_S` + Adjusts the delay between sensor readings. Set to an integer value + (seconds). + + Default value is `60` seconds. + +### Remote Procedure Call (RPC) Service + +The following RPCs can be initiated in the Remote Procedure Call menu of +the [Golioth Console](https://console.golioth.io). + + - `get_network_info` + Query and return network information. + + - `reboot` + Reboot the system. + + - `set_log_level` + Set the log level. + + The method takes a single parameter which can be one of the + following integer values: + + - `0`: `LOG_LEVEL_NONE` + - `1`: `LOG_LEVEL_ERR` + - `2`: `LOG_LEVEL_WRN` + - `3`: `LOG_LEVEL_INF` + - `4`: `LOG_LEVEL_DBG` + +### Time-Series Stream data + +Sensor data is periodically sent to the following `sensor/*` paths of +the LightDB Stream service: + + - `sensor/temperature/celcius`: Temperature (°C) + - `sensor/temperature/farenheight`: Temperature (°F) + - `sensor/x_axis/acceleration/crest_factor`: X-Axis Crest Factor + - `sensor/x_axis/acceleration/high_frequency_rms`: X-Axis + High-Frequency RMS Acceleration (G) + - `sensor/x_axis/acceleration/kurtosis`: X-Axis Kurtosis + - `sensor/x_axis/acceleration/peak`: X-Axis Peak Acceleration (G) + - `sensor/x_axis/acceleration/rms`: X-Axis RMS Acceleration (G) + - `sensor/x_axis/velocity/peak/frequency`: X-Axis Peak Velocity + Component Frequency (Hz) + - `sensor/x_axis/velocity/peak/in_per_sec`: X-Axis Peak Velocity + (in/sec) + - `sensor/x_axis/velocity/peak/mm_per_sec`: X-Axis Peak Velocity + (mm/sec) + - `sensor/x_axis/velocity/rms/in_per_sec`: X-Axis RMS Velocity + (in/sec) + - `sensor/x_axis/velocity/rms/mm_per_sec`: X-Axis RMS Velocity + (mm/sec) + - `sensor/x_axis/acceleration/crest_factor`: X-Axis Crest Factor + - `sensor/x_axis/acceleration/high_frequency_rms`: X-Axis + High-Frequency RMS Acceleration (G) + - `sensor/z_axis//acceleration/kurtosis`: X-Axis Kurtosis + - `sensor/z_axis//acceleration/peak`: Z-Axis Peak Acceleration (G) + - `sensor/z_axis//acceleration/rms`: Z-Axis RMS Acceleration (G) + - `sensor/z_axis//velocity/peak/frequency`: Z-Axis Peak Velocity + Component Frequency (Hz) + - `sensor/z_axis//velocity/peak/in_per_sec`: Z-Axis Peak Velocity + (in/sec) + - `sensor/z_axis//velocity/peak/mm_per_sec`: Z-Axis Peak Velocity + (mm/sec) + - `sensor/z_axis//velocity/rms/in_per_sec`: Z-Axis RMS Velocity + (in/sec) + - `sensor/z_axis//velocity/rms/mm_per_sec`: Z-Axis RMS Velocity + (mm/sec) + +``` json +{ + "sensor": { + "temperature": { + "celcius": 27.08 + }, + "x_axis": { + "acceleration": { + "crest_factor": 12.258, + "high_frequency_rms": 0.007, + "kurtosis": 25.063, + "peak": 0.09, + "rms": 0.007 + }, + "velocity": { + "peak": { + "frequency": 12.2, + "mm_per_sec": 0.19 + }, + "rms": { + "mm_per_sec": 0.134 + } + } + }, + "z_axis": { + "acceleration": { + "crest_factor": 3.986, + "high_frequency_rms": 0.019, + "kurtosis": 3.231, + "peak": 0.078, + "rms": 0.248 + }, + "velocity": { + "peak": { + "frequency": 9.7, + "mm_per_sec": 25.453 + }, + "rms": { + "mm_per_sec": 17.998 + } + } + } + } +} +``` + +If your board includes a battery, voltage and level readings +will be sent to the `battery` path. + +> [!NOTE] +> Your Golioth project must have a Pipeline enabled to receive this +> data. See the [Add Pipeline to Golioth](#add-pipeline-to-golioth) +> section below. + +### Stateful Data (LightDB State) + +The concept of Digital Twin is demonstrated with the LightDB State +`example_int0` and `example_int1` variables that are subpaths of the +`desired` and `state` paths. + + - `desired` values may be changed from the cloud side. The device will + recognize these, validate them for \[0..65535\] bounding, and then + reset these values to `-1` + - `state` values will be updated by the device to reflect the device's + actual stored value. The cloud may read the `state` endpoints to + determine device status. In this arrangement, only the device + should ever write to the `state` endpoints. + +``` json +{ + "desired": { + "example_int0": -1, + "example_int1": -1 + }, + "state": { + "example_int0": 0, + "example_int1": 1 + } +} +``` + +By default the state values will be `0` and `1`. Try updating the +`desired` values and observe how the device updates its state. + +### OTA Firmware Update + +This application includes the ability to perform Over-the-Air (OTA) +firmware updates. To do so, you need a binary compiled with a different +version number than what is currently running on the device. + +> [!NOTE] +> If a newer release is available than what your device is currently +> running, you may download the pre-compiled binary that ends in +> `_update.bin` and use it in step 2 below. + +1. Update the version number in the `VERSION` file and perform a + pristine (important) build to incorporate the version change. +2. Upload the `build/app/zephyr/zephyr.signed.bin` file as a Package for + your Golioth project. + + - Use `main` as the package name. + - Use the same version number from step 1. + +3. Create a Cohort and add your device to it. +4. Create a Deployment for your Cohort using the package name and + version number from step 2. +5. Devices in your Cohort will automatically upgrade to the most + recently deployed firmware. + +Visit [the Golioth Docs OTA Firmware Upgrade +page](https://docs.golioth.io/firmware/golioth-firmware-sdk/firmware-upgrade/firmware-upgrade) +for more info. + +## Add Pipeline to Golioth + +Golioth uses [Pipelines](https://docs.golioth.io/data-routing) to route +stream data. This gives you flexibility to change your data routing +without requiring updated device firmware. + +Whenever sending stream data, you must enable a pipeline in your Golioth +project to configure how that data is handled. Add the contents of +`pipelines/json-to-lightdb.yml` as a new pipeline as follows (note that +this is the default pipeline for new projects and may already be +present): + +1. Navigate to your project on the Golioth web console. +2. Select `Pipelines` from the left sidebar and click the `Create` + button. +3. Give your new pipeline a name and paste the pipeline configuration + into the editor. +4. Click the toggle in the bottom right to enable the pipeline and + then click `Create`. + +All data streamed to Golioth in JSON format will now be routed to +LightDB Stream and may be viewed using the web console. You may change +this behavior at any time without updating firmware simply by editing +this pipeline entry. + +## Local set up + +> [!IMPORTANT] +> Do not clone this repo using git. Zephyr's `west` meta tool should be +> used to set up your local workspace. + +### Install the Python virtual environment (recommended) + +``` shell +cd ~ +mkdir golioth-reference-design-modbus-vibration-monitor +python -m venv golioth-reference-design-modbus-vibration-monitor/.venv +source golioth-reference-design-modbus-vibration-monitor/.venv/bin/activate +pip install wheel west ecdsa +``` + +### Use `west` to initialize and install + +``` shell +cd ~/golioth-reference-design-modbus-vibration-monitor +west init -m git@github.com:golioth/reference-design-modbus-vibration-monitor.git . +west update +west zephyr-export +pip install -r deps/zephyr/scripts/requirements.txt +``` + +## Building the application + +Build the Zephyr sample application for the [Nordic nRF9160 +DK](https://www.nordicsemi.com/Products/Development-hardware/nrf9160-dk) +(`nrf9160dk_nrf9160_ns`) from the top level of your project. After a +successful build you will see a new `build` directory. Note that any +changes (and git commits) to the project itself will be inside the `app` +folder. The `build` and `deps` directories being one level higher +prevents the repo from cataloging all of the changes to the dependencies +and the build (so no `.gitignore` is needed). + +### Use `west` to initialize the workspace and install dependencies + +> [!WARNING] +> You must perform a pristine build (use `-p` or remove the `build` +> directory) after changing the firmware version number in the `VERSION` +> file for the change to take effect. + +``` text +$ (.venv) west build -p -b nrf9160dk/nrf9160/ns --sysbuild app +$ (.venv) west flash +``` + +Configure PSK-ID and PSK using the device shell based on your Golioth +credentials and reboot: + +``` text +uart:~$ settings set golioth/psk-id +uart:~$ settings set golioth/psk +uart:~$ kernel reboot cold +``` + +## External Libraries + +The following code libraries are installed by default. If you are not +using the custom hardware to which they apply, you can safely remove +these repositories from `west.yml` and remove the includes/function +calls from the C code. + + - [golioth-zephyr-boards](https://github.com/golioth/golioth-zephyr-boards) + includes the board definitions for the Golioth Aludel-Mini + - [libostentus](https://github.com/golioth/libostentus) is a helper + library for controlling the Ostentus ePaper faceplate + - [zephyr-network-info](https://github.com/golioth/zephyr-network-info) + is a helper library for querying, formatting, and returning network + connection information via Zephyr log or Golioth RPC + +## Have Questions? + +Please get in touch with Golioth engineers by starting a new thread on +the [Golioth Forum](https://forum.golioth.io/). diff --git a/README.rst b/README.rst deleted file mode 100644 index dd89fae..0000000 --- a/README.rst +++ /dev/null @@ -1,346 +0,0 @@ -.. - Copyright (c) 2024 Golioth, Inc. - SPDX-License-Identifier: Apache-2.0 - -Golioth Reference Design - Modbus Vibration Monitor -################################################### - -This repository contains the firmware source code and `pre-built release -firmware images `_ for the Golioth Modbus Vibration Monitor reference -design. - -The full project details are available on the `Modbus Vibration Monitor Project -Page`_, including follow-along guides for building an IoT Modbus Vibration -Monitor yourself using widely available off-the-shelf development boards. - -We call this **Follow-Along Hardware**, and we think it's one of the quickest -and easiest ways to get started building an IoT proof-of-concept with Golioth. -In the follow-along guides, you will learn how to assemble the hardware, flash a -pre-built firmware image onto the device, and connect to the Golioth cloud in -minutes. - -Once you have completed a follow-along guide for one of our supported hardware -platforms, the instructions below will walk you through how to build and -configure the firmware yourself. - -Supported Hardware -****************** - -This firmware can be built for a variety of supported hardware platforms. - -.. pull-quote:: - [!IMPORTANT] - - In Zephyr, each of these different hardware variants is given a unique - "board" identifier, which is used by the build system to generate firmware - for that variant. - - When building firmware using the instructions below, make sure to use the - correct Zephyr board identifier that corresponds to your follow-along - hardware platform. - -.. list-table:: **Follow-Along Hardware** - :header-rows: 1 - - * - Hardware - - Zephyr Board - - Follow-Along Guide - - * - .. image:: images/modbus_vibration_monitor_fah_nrf9160_dk.jpg - :width: 240 - - ``nrf9160dk_nrf9160_ns`` - - `nRF9160 DK Follow-Along Guide`_ - -.. list-table:: **Custom Golioth Hardware** - :header-rows: 1 - - * - Hardware - - Zephyr Board - - Project Page - * - .. image:: images/modbus_vibration_monitor_aludel_mini_v1_photo_top.jpg - :width: 240 - - ``aludel_mini_v1_sparkfun9160_ns`` - - `Modbus Vibration Monitor Project Page`_ - * - .. image:: images/modbus_vibration_monitor_aludel_mini_v1_photo_top.jpg - :width: 240 - - ``aludel_elixir_ns`` - - - -Firmware Overview -***************** - -This reference design firmware demonstrates how to interface with a `Banner Sure -Cross® QM30VT2`_ sensor via the Modbus protocol and send vibration and -temperature measurements to the cloud using the Golioth IoT platform. - -Sensor values are uploaded to the LightDB stream database in the Golioth -Cloud. The sensor sampling frequency and other sensor parameters are remotely -configurable via the Golioth Settings service. - -Supported Golioth Zephyr SDK Features -===================================== - -This firmware implements the following features from the Golioth Zephyr SDK: - -- `Device Settings Service `_ -- `LightDB State Client `_ -- `LightDB Stream Client `_ -- `Logging Client `_ -- `Over-the-Air (OTA) Firmware Upgrade `_ -- `Remote Procedure Call (RPC) `_ - -Device Settings Service ------------------------ - -The following settings can be set in the Device Settings menu of the `Golioth -Console`_. - -``LOOP_DELAY_S`` - Adjusts the delay between sensor readings. Set to an integer value (seconds). - - Default value is ``60`` seconds. - -LightDB Stream Service ----------------------- - -Sensor data is periodically sent to the following ``sensor/*`` endpoints of the -LightDB Stream service: - -* ``sensor/temperature/celcius``: Temperature (°C) -* ``sensor/temperature/farenheight``: Temperature (°F) -* ``sensor/x_axis/acceleration/crest_factor``: X-Axis Crest Factor -* ``sensor/x_axis/acceleration/high_frequency_rms``: X-Axis High-Frequency RMS - Acceleration (G) -* ``sensor/x_axis/acceleration/kurtosis``: X-Axis Kurtosis -* ``sensor/x_axis/acceleration/peak``: X-Axis Peak Acceleration (G) -* ``sensor/x_axis/acceleration/rms``: X-Axis RMS Acceleration (G) -* ``sensor/x_axis/velocity/peak/frequency``: X-Axis Peak Velocity Component - Frequency (Hz) -* ``sensor/x_axis/velocity/peak/in_per_sec``: X-Axis Peak Velocity (in/sec) -* ``sensor/x_axis/velocity/peak/mm_per_sec``: X-Axis Peak Velocity (mm/sec) -* ``sensor/x_axis/velocity/rms/in_per_sec``: X-Axis RMS Velocity (in/sec) -* ``sensor/x_axis/velocity/rms/mm_per_sec``: X-Axis RMS Velocity (mm/sec) -* ``sensor/x_axis/acceleration/crest_factor``: X-Axis Crest Factor -* ``sensor/x_axis/acceleration/high_frequency_rms``: X-Axis High-Frequency RMS - Acceleration (G) -* ``sensor/z_axis//acceleration/kurtosis``: X-Axis Kurtosis -* ``sensor/z_axis//acceleration/peak``: Z-Axis Peak Acceleration (G) -* ``sensor/z_axis//acceleration/rms``: Z-Axis RMS Acceleration (G) -* ``sensor/z_axis//velocity/peak/frequency``: Z-Axis Peak Velocity Component - Frequency (Hz) -* ``sensor/z_axis//velocity/peak/in_per_sec``: Z-Axis Peak Velocity (in/sec) -* ``sensor/z_axis//velocity/peak/mm_per_sec``: Z-Axis Peak Velocity (mm/sec) -* ``sensor/z_axis//velocity/rms/in_per_sec``: Z-Axis RMS Velocity (in/sec) -* ``sensor/z_axis//velocity/rms/mm_per_sec``: Z-Axis RMS Velocity (mm/sec) - -On hardware platforms with support for battery monitoring, battery voltage and -level readings are periodically sent to the following ``battery/*`` endpoints: - -* ``battery/batt_v``: Battery Voltage (V) -* ``battery/batt_lvl``: Battery Level (%) - -LightDB State Service ---------------------- - -The concept of Digital Twin is demonstrated with the LightDB State -``example_int0`` and ``example_int1`` variables that are members of the -``desired`` and ``state`` endpoints. - -* ``desired`` values may be changed from the cloud side. The device will - recognize these, validate them for [0..65535] bounding, and then reset these - endpoints to ``-1`` - -* ``state`` values will be updated by the device whenever a valid value is - received from the ``desired`` endpoints. The cloud may read the ``state`` - endpoints to determine device status, but only the device should ever write to - the ``state`` endpoints. - -Remote Procedure Call (RPC) Service ------------------------------------ - -The following RPCs can be initiated in the Remote Procedure Call menu of the -`Golioth Console`_. - -``get_network_info`` - Query and return network information. - -``reboot`` - Reboot the system. - -``set_log_level`` - Set the log level. - - The method takes a single parameter which can be one of the following integer - values: - - * ``0``: ``LOG_LEVEL_NONE`` - * ``1``: ``LOG_LEVEL_ERR`` - * ``2``: ``LOG_LEVEL_WRN`` - * ``3``: ``LOG_LEVEL_INF`` - * ``4``: ``LOG_LEVEL_DBG`` - -Building the firmware -********************* - -The firmware build instructions below assume you have already set up a Zephyr -development environment and have some basic familiarity with building firmware -using the Zephyr Real Time Operating System (RTOS). - -If you're brand new to building firmware with Zephyr, you will need to follow -the `Zephyr Getting Started Guide`_ to install the Zephyr SDK and related -dependencies. - -We also provide free online `Developer Training`_ for Zephyr at: - -https://training.golioth.io/docs/zephyr-training - -.. pull-quote:: - [!IMPORTANT] - - Do not clone this repo using git. Zephyr's ``west`` meta-tool should be used - to set up your local workspace. - -Create a Python virtual environment (recommended) -================================================= - -.. code-block:: shell - - cd ~ - mkdir golioth-reference-design-modbus-vibration-monitor - python -m venv golioth-reference-design-modbus-vibration-monitor/.venv - source golioth-reference-design-modbus-vibration-monitor/.venv/bin/activate - -Install ``west`` meta-tool -========================== - -.. code-block:: shell - - pip install wheel west - -Use ``west`` to initialize the workspace and install dependencies -================================================================= - -.. code-block:: shell - - cd ~/golioth-reference-design-modbus-vibration-monitor - west init -m git@github.com:golioth/reference-design-modbus-vibration-monitor.git . - west update - west zephyr-export - pip install -r deps/zephyr/scripts/requirements.txt - -Build the firmware -================== - -Build the Zephyr firmware from the top-level workspace of your project. After a -successful build you will see a new ``build/`` directory. - -Note that this git repository was cloned into the ``app`` folder, so any changes -you make to the application itself should be committed inside this repository. -The ``build`` and ``deps`` directories in the root of the workspace are managed -outside of this git repository by the ``west`` meta-tool. - -Prior to building, update ``CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION`` in the -``prj.conf`` file to reflect the firmware version number you want to assign to -this build. - -.. pull-quote:: - [!IMPORTANT] - - When running the commands below, make sure to replace the placeholder - ```` with the actual Zephyr board from the table above - that matches your follow-along hardware. - -.. code-block:: text - - $ (.venv) west build -p -b app - -For example, to build firmware for the `Nordic nRF9160 DK`_-based follow-along -hardware: - -.. code-block:: text - - $ (.venv) west build -p -b nrf9160dk_nrf9160_ns app - -Flash the firmware -================== - -.. code-block:: text - - $ (.venv) west flash - -Provision the device -==================== - -In order for the device to securely authenticate with the Golioth Cloud, we need -to provision the device with a pre-shared key (PSK). This key will persist -across reboots and only needs to be set once after the device firmware has been -programmed. In addition, flashing new firmware images with ``west flash`` should -not erase these stored settings unless the entire device flash is erased. - -Configure the PSK-ID and PSK using the device UART shell and reboot the device: - -.. code-block:: text - - uart:~$ settings set golioth/psk-id - uart:~$ settings set golioth/psk - uart:~$ kernel reboot cold - -External Libraries -****************** - -The following code libraries are installed by default. If you are not using the -custom hardware to which they apply, you can safely remove these repositories -from ``west.yml`` and remove the includes/function calls from the C code. - -* `golioth-zephyr-boards`_ includes the board definitions for the Golioth - Aludel-Mini -* `libostentus`_ is a helper library for controlling the Ostentus ePaper - faceplate -* `zephyr-network-info`_ is a helper library for querying, formatting, and - returning network connection information via Zephyr log or Golioth RPC - -Pulling in updates from the Reference Design Template -***************************************************** - -This reference design was forked from the `Reference Design Template`_ repo. We -recommend the following workflow to pull in future changes: - -* Setup - - * Create a ``template`` remote based on the Reference Design Template - repository - -* Merge in template changes - - * Fetch template changes and tags - * Merge template release tag into your ``main`` (or other branch) - * Resolve merge conflicts (if any) and commit to your repository - -.. code-block:: shell - - # Setup - git remote add template https://github.com/golioth/reference-design-template.git - git fetch template --tags - - # Merge in template changes - git fetch template --tags - git checkout your_local_branch - git merge template_v1.0.0 - - # Resolve merge conflicts if necessary - git add resolved_files - git commit - -.. _Golioth Console: https://console.golioth.io -.. _Nordic nRF9160 DK: https://www.nordicsemi.com/Products/Development-hardware/nrf9160-dk -.. _golioth-zephyr-boards: https://github.com/golioth/golioth-zephyr-boards -.. _libostentus: https://github.com/golioth/libostentus -.. _zephyr-network-info: https://github.com/golioth/zephyr-network-info -.. _Reference Design Template: https://github.com/golioth/reference-design-template -.. _Modbus Vibration Monitor Project Page: https://projects.golioth.io/reference-designs/modbus-vibration-monitor -.. _nRF9160 DK Follow-Along Guide: https://projects.golioth.io/reference-designs/modbus-vibration-monitor/guide-nrf9160-dk -.. _releases: https://github.com/golioth/reference-design-modbus-vibration-monitor/releases -.. _Zephyr Getting Started Guide: https://docs.zephyrproject.org/latest/develop/getting_started/ -.. _Developer Training: https://training.golioth.io -.. _SemVer: https://semver.org -.. _Banner Sure Cross® QM30VT2: https://www.bannerengineering.com/us/en/products/part.806276.html diff --git a/images/modbus_vibration_monitor_aludel_mini_v1_photo_top.jpg b/images/modbus_vibration_monitor_aludel_mini_v1_photo_top.jpg deleted file mode 100644 index d8c3fe2..0000000 Binary files a/images/modbus_vibration_monitor_aludel_mini_v1_photo_top.jpg and /dev/null differ diff --git a/images/modbus_vibration_monitor_fah_nrf9160_dk.jpg b/images/modbus_vibration_monitor_fah_nrf9160_dk.jpg deleted file mode 100644 index 4dfe92a..0000000 Binary files a/images/modbus_vibration_monitor_fah_nrf9160_dk.jpg and /dev/null differ