.. Copyright (c) 2024 Golioth, Inc. SPDX-License-Identifier: Apache-2.0
Golioth Reference Design Template #################################
Overview
Use this repo as a template when beginning work on a new Golioth Reference
Design. It is set up as a standalone repository, with all Golioth features
implemented in basic form. Search the project for the word template
and
rd_template
and update those occurrences with your reference design's name.
Local set up
.. pull-quote:: [!IMPORTANT]
Do not clone this repo using git. Zephyr's west
meta tool should be used to
set up your local workspace.
.. code-block:: shell
cd ~ mkdir golioth-reference-design-template python -m venv golioth-reference-design-template/.venv source golioth-reference-design-template/.venv/bin/activate pip install wheel west
west
to initialize and install.. code-block:: shell
cd ~/golioth-reference-design-template west init -m git@github.com:golioth/reference-design-template.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
_
(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).
Prior to building, update VERSION
file to reflect the firmware version number you want to assign
to this build. Then run the following commands to build and program the firmware onto the device.
.. pull-quote:: [!IMPORTANT]
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.
.. code-block:: 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:
.. code-block:: text
uart:~$ settings set golioth/psk-id my-psk-id@my-project
uart:~$ settings set golioth/psk
Add Pipeline to Golioth
Golioth uses Pipelines
_ 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/cbor-to-lightdb.yml
as a new pipeline as
follows (note that this is the default pipeline for new projects and may already be present):
Pipelines
from the left sidebar and click the Create
button.Create
.All data streamed to Golioth in CBOR 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.
Golioth Features
This app currently implements Over-the-Air (OTA) firmware updates, Settings Service, Logging, RPC, and both LightDB State and LightDB Stream data.
The following settings should 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.
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
An up-counting timer is periodically sent to the sensor/counter
endpoint of the
LightDB Stream service to simulate sensor data. If your board includes a
battery, voltage and level readings will be sent to the battery
endpoint.
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.
Please refer to the comments in each header file for a service-by-service explanation of this template.
Hardware Variations
This reference design may be built for a variety of different boards.
Prior to building, update VERSION
file to reflect the firmware version number you want to assign
to this build. Then run the following commands to build and program the firmware onto the device.
This reference design may be built for the Golioth Aludel Mini board.
.. code-block:: text
$ (.venv) west build -p -b aludel_mini/nrf9160/ns --sysbuild app $ (.venv) west flash
This reference design may be built for the Golioth Aludel Elixir board. By default this will build for the latest hardware revision of this board.
.. code-block:: text
$ (.venv) west build -p -b aludel_elixir/nrf9160/ns --sysbuild app $ (.venv) west flash
To build for a specific board revision (e.g. Rev A) add the revision suffix @<rev>
.
.. code-block:: text
$ (.venv) west build -p -b aludel_elixir@A/nrf9160/ns --sysbuild app $ (.venv) west flash
OTA Firmware Update
This application includes the ability to perform Over-the-Air (OTA) firmware updates:
VERSION
file and perform a pristine (important) build to
incorporate the version change.build/app/zephyr/zephyr.signed.bin
file as an artifact for your Golioth project
using main
as the package name.Visit the Golioth Docs OTA Firmware Upgrade page
_ for more info.
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-Minilibostentus
_ is a helper library for controlling the Ostentus ePaper
faceplatezephyr-network-info
_ is a helper library for querying, formatting, and returning network
connection information via Zephyr log or Golioth RPCUsing this template to start a new project
Fork this template to create your own Reference Design. After checking out your fork, we recommend the following workflow to pull in future changes:
Setup
template
remote based on the Reference Design Template repositoryMerge in template changes
main
(or other branch).. code-block:: shell
git remote add template https://github.com/golioth/reference-design-template.git git fetch template --tags
git fetch template --tags git checkout your_local_branch git merge template_v1.0.0
git add resolved_files git commit
.. _Golioth Console: https://console.golioth.io .. _Nordic nRF9160 DK: https://www.nordicsemi.com/Products/Development-hardware/nrf9160-dk .. _Pipelines: https://docs.golioth.io/data-routing .. _the Golioth Docs OTA Firmware Upgrade page: https://docs.golioth.io/firmware/golioth-firmware-sdk/firmware-upgrade/firmware-upgrade .. _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