This repository contains the firmware source code and pre-built release firmware images for the Golioth OpenThread Demo.
The full project details are available on the Golioth Thread Demo Project Page.
- Golioth device PSK credentials
- A running Thread Border Router with NAT64 translation (we will be using the commercially available off-the-shelf GL-S200 Thread Border Router)
- Thread Network Name and Network Key
This firmware can be built for a variety of supported hardware platforms.
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 hardware platform.
Development Borad | Zephyr Board |
---|---|
nrf52840dk_nrf52840 |
Development Board | Zephyr Board |
---|---|
adafruit_feather_nrf52840 |
This is a Reference Design for a Thread Protocol enabled device using Zephyr and connecting to Golioth over IPv6.
Configure the following Kconfig options:
- OPENTHREAD_NETWORK_NAME - Name of your Thread network
- OPENTHREAD_NETWORKKEY - Network Key of your Thread network
by changing these lines in the prj.conf
configuration file, e.g.:
CONFIG_OPENTHREAD_NETWORKKEY="00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff"
CONFIG_OPENTHREAD_NETWORK_NAME="golioth-thread"
CONFIG_OPENTHREAD_CHANNEL
is set to 26
.
Important
Make sure the Thread Network Name, Thread Network Key and Thread Channel match your Border Router configuration.
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)
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.
An up-counting timer is periodically sent to the sensor/counter
endpoint of the
LightDB Stream service to simulate sensor data.
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 thedesired
endpoints. The cloud may read thestate
endpoints to determine device status, but only the device should ever write to thestate
endpoints.
The following RPCs can be initiated in the Remote Procedure Call menu of the Golioth Console.
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
Do not clone this repo using git. Zephyr's west
meta tool should be used to
set up your local workspace.
cd ~
mkdir golioth-openthread-demo
python -m venv golioth-openthread-demo/.venv
source golioth-openthread-demo/.venv/bin/activate
pip install wheel west
cd ~/golioth-openthread-demo
west init -m git@github.com:golioth/golioth-openthread-demo.git .
west update
west zephyr-export
pip install -r deps/zephyr/scripts/requirements.txt
Build the Zephyr sample application 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. Then run the following
commands to build and program the firmware onto the device.
Important
When running the commands below, make sure to replace the placeholder
<your_zephyr_board_id>
with the actual Zephyr board from the table above
that matches your hardware.
In addition, replace <your.semantic.version>
with a SemVer-compliant
version string (e.g. 1.2.3
) that will be used by the DFU service when
checking for firmware updates.
$ (.venv) west build -p -b <your_zephyr_board_id> app
For example, to build firmware for the Nordic nRF52840 DK-based follow-along hardware:
$ (.venv) west build -p -b nrf52840dk_nrf52840 app
$ (.venv) west flash
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:
uart:~$ settings set golioth/psk-id <my-psk-id@my-project>
uart:~$ settings set golioth/psk <my-psk>
uart:~$ kernel reboot cold
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
- Create a
- 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
# 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