This firmware was developed for use in the Off-grid Cellular Water Level Monitor project by Jeremy Cook submitted to the Unveil the Unseen with Nordic Semiconductor Hackster contest.
The cloud infrastructure configuration required for this firmware is documented separately in the Remote water level monitoring firmware for Thingy:91 X Hackster project by Chris Wilson.
Tip
Since the Hackster.io website currently has some bugs (e.g. loading images on mobile fails sometimes, code highlighting doesn't work, etc.), a copy of the Markdown source for the Hackster project page is included in this repository at hackster_project/story.md (it may be easier to read on GitHub).
This repository was originally generated from v1.6.0 of the Golioth Thingy91 Example Program template, but has been updated to use v0.19.1 of the Golioth Firmware SDK.
- Hackster Water Level Sensor
The device uses the low-power accelerometer on the Nordic Thingy:91 X cellular IoT prototyping platform to measure the pitch angle ψ of hinged float arm. The height of the float (relative to the hinge) is calculated based on the pitch angle ψ and the length of the float arm, which is configurable at runtime for each device via the Golioth web console setting FLOAT_LENGTH.
Important
This initial prototype firmware makes an important assumption that the device is relatively static (water level changes very slowly over time) and is not subject to any other acceleration except the acceleration due to gravity. Any acceleration applied to the device due to waves, vibrations, etc. will result in inaccurate height calculations!
This app implements the following features provided by Golioth:
- Device Settings Service
- Stream Client
- Over-the-Air (OTA) Firmware Upgrade
- Backend Logging (only enabled in debug configurations)
The following settings should be set in the Device Settings menu of the Golioth Console.
STREAM_DELAY_SDelay between sending water level sensor readings to Golioth. Set to an integer value (seconds). Defaults to900seconds (15 min).FLOAT_LENGTHThe length of the float arm measured from the center of the hinge to the point where the arm touches the surface of the water. Set to a floating point value (inches). Defaults to0.FLOAT_OFFSETAn offset value added to the measured float height. Set to a floating point value (inches). Defaults to0.ACCEL_NUM_SAMPLESTotal number of accelerometer samples used to calculate the float angle. Set to an integer value. Defaults to100.ACCEL_SAMPLE_DELAY_MSDelay between reading each accelerometer sample. Set to an integer value (milliseconds). Defaults to100.
Sensor data is sent to Golioth periodically based on the STREAM_DELAY_S device setting. Data may be viewed in the Golioth Console by viewing the "LightDB Stream" tab of the device, or the in the Project's "Monitor" section on the left sidebar.
Below you will find sample stream data generated by this application.
{
"sensor": {
"accel": {
"x": 0.058554390000000026,
"y": 4.138562519999999,
"z": -8.99671413
},
"battery": {
"current": 0.00800000037997961,
"soc": 98.61529541015625,
"temp": 29.631591796875,
"tte": -1,
"ttf": -1,
"voltage": 4.178999900817871
},
"tilt": {
"pitch": -24.702358580343013,
"roll": -0.338775599397565
},
"water_level": {
"float_height": 8.012202842633396,
"float_length": 44,
"float_offset": 26.399999618530273
}
}
}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 _zephyr.signed.bin and use it in step 2 below.
- Update the version number in the
VERSIONfile and perform a pristine (-p) build to incorporate the version change. - Upload the
*_zephyr.signed.binfile as a Package in your Golioth project.- Use
thingy91xas the package name (this package name is defined inboards/thingy91x_nrf9151_ns.conf). - Use the same version number from step 1 (Golioth should automatically detect the version number).
- Use
- Create a Cohort for your device type (e.g.
prototypes) - Create a Deployment for your Cohort using the package name and version number from step 2.
- Devices in your Cohort will automatically upgrade to the most recently deployed firmware.
Visit the Golioth Docs OTA Firmware Upgrade page for more info.
Golioth uses Pipelines to route stream data. This gives you flexibility to change your data routing without requiring updated device firmware.
When 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-with-path.yml as a new pipeline as follows (note that this is the default pipeline for new projects and may already be present):
- Navigate to your project on the Golioth web console.
- Select
Pipelinesfrom the left sidebar and click theCreatebutton. - Give your new pipeline a name and paste the pipeline configuration into the editor.
- Click the toggle in the bottom right to enable the pipeline and then click
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.
The application firmware requires the PSK credentials generated by Golioth to be programmed into the nRF9151 secure credential storage. The easiest way to do this is to use the Certificate Manager GUI built into the Cellular Monitor app provided by the nRF Connect for Desktop software.
The Cellular Monitor app communicates with the device via AT commands. Nordic provides a pre-built at_client firmware image that is compatible with the Cellular Monitor app.
Note
The Connectivity Bridge and modem firmware below only need to be programmed once. The application firmware can be reprogrammed in the future without affecting the other firmware images.
The Thingy:91 X has an onboard nRF5340 SoC that needs to be programmed with the Connectivity Bridge firmware from Nordic.
Follow the Updating the firmware on the nRF5340 SoC guide from Nordic to program the Connectivity Bridge firmware on the nRF5340.
Important
When following the guide linked above, make sure to download and flash the pre-compiled Connectivity Bridge firmware binaries from the v3.0.0 release or later of the hello-nrfcloud/firmware project. Previous versions have a bug that results in garbled serial output on the USB-to-UART port).
This application was tested using the mfw_nrf91x1_2.0.2.zip modem firmware.
Follow the Updating the modem firmware on the nRF9151 SiP guide from Nordic to update the modem firmware on the nRF9151 SiP.
The pre-compiled at_client firmware is included in the thingy91x_mfw-2.0.2_sdk-3.0.0.zip package from Nordic. Make sure to program the img_app_bl/thingy91x_at_client_2025-05-08_3bfc4657.hex firmware when flashing the firmware.
Follow the Updating the application firmware on the nRF9151 SiP guide from Nordic to install the at_client firmware on the nRF9151 SiP.
Next, open the Cellular Monitor app.
Open the CERTIFICATE MANAGER tab in the Cellular Monitor app and select the Thingy:91 X device from the top left.
Provide the PSK-ID and PSK for the device from the Device Credentials tab in the Golioth Console. Note that the PSK value from the Golioth Console must be converted from a string to hex before writing it to the device.
Finally, set the security tag to match the value of GOLIOTH_COAP_CLIENT_CREDENTIALS_TAG (i.e. 515765868) and click the "Update certificate" button.
Use the Serial Terminal app to verify the certificate was programmed correctly.
Run the AT%CMNG=1 command in the Terminal screen to list all stored certificates. There should be two entries matching the security tag that was specified. If there is only one entry, press the "Update certificates" button again in the certificate manager window.
Now that the Golioth PSK credentials have been programmed, the at_client firmware can be replaced with water level monitoring firmware from this project.
The latest application firmware can be downloaded from the Releases page in this repository.
Follow the Updating the application firmware on the nRF9151 SiP guide from Nordic to install the firmware on the nRF9151 SiP.
For example, to program the v2.5.1 firmware over USB via MCUboot (DFU), run the following commands.
nrfutil device list
nrfutil device program \
--firmware hackster-water-level-sensor_v2.5.1_thingy91x_nrf9151_ns_dfu_application.zip \
--serial-number THINGY91X_3FCE94805D7 \
--options verify=VERIFY_READ,reset=RESET_DEFAULTTo program the v2.5.1 firmware via SWD through an external debug probe, run the following commands (specify --serial-number <j-link-serial-number> if more than one device are connected).
nrfutil device recover
nrfutil device program \
--firmware hackster-water-level-sensor_v2.5.1_thingy91x_nrf9151_ns_merged.hex \
--traits jlink \
--x-family nrf91 \
--core Application \
--options verify=VERIFY_READ,reset=RESET_DEFAULTThis section describes how to set up a local development environment for building and flashing the firmware.
Important
Do not clone this repo using git. Zephyr's west meta tool should be used to set up your local workspace.
The Golioth Firmware SDK used in this firmware depends on Nordic's nRF Connect SDK (NCS) which integrates Zephyr RTOS.
Note
The nRF Connect SDK includes everything that is required by Zephyr’s Getting Started Guide together with additional tools and Python dependencies that the nRF Connect SDK uses.
To build this firmware, the correct version of the nRF Connect SDK toolchain needs to be installed. The nRF Connect SDK toolchain includes the Zephyr SDK and then adds tools and modules required to build nRF Connect SDK samples and applications on top of it.
This firmware currently depends on v0.19.1 of the golioth-firmware-sdk, which requires v3.0.1 of the nRF Connect SDK. (The NCS version required by the Golioth SDK is defined in https://github.com/golioth/golioth-firmware-sdk/blob/main/west-ncs.yml)
Follow instructions at the following URL to install v3.0.1 the nRF Connect SDK toolchain for your operating system:
https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/installation.html
When you get to the step "Get the nRF Connect SDK code", instruct west to initialize this repository instead of the nRF Connect SDK (this repository will pull in NCS as a dependency).
The whole workflow looks like this:
# Start the NCS toolchain environment
nrfutil sdk-manager toolchain launch --ncs-version v3.0.1 --shell
# On Windows, use this command to start the NCS toolchain environment
nrfutil sdk-manager toolchain launch --ncs-version v3.0.1 --terminal
# Create a workspace directory for the project
mkdir ~/hackster-water-level-sensor
# Change directory into the workspace
cd ~/hackster-water-level-sensor
# Use west to initialize the workspace
west init -m [email protected]:cgnd/hackster-water-level-sensor.git
# Use west to clone the project repositories
west update
# Export a Zephyr CMake package
west zephyr-export
# Set up the command-line build environment
source deps/zephyr/zephyr-env.shTip
To learn how to automatically start the NCS toolchain environment when entering the project workspace, check out this repo.
Prior to building, update the 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.
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.
cd ~/hackster-water-level-sensor/app
west build -p -b thingy91x/nrf9151/ns --sysbuild
The firmware built in the previous step can be flashed to the device via a SWD programmer (e.g. a Segger J-Link) using the following command:
west flash --recoverThe default prj.conf disables the serial console and remote logging to reduce power consumption.
To enable serial debug logging output and the Zephyr shell on the Thingy:91 X, enable the overlay-serial-debug.conf overlay.
west build -p -b thingy91x/nrf9151/ns --sysbuild --extra-conf overlay-serial-debug.confTo enable remote logging to the Golioth Console, enable the overlay-golioth-logging.conf overlay.
west build -p -b thingy91x/nrf9151/ns --sysbuild --extra-conf overlay-golioth-logging.confTo enable configuring the Golioth PSK credentials via the Zephyr shell, enable the overlay-golioth-runtime-psk.conf overlay.
west build -p -b thingy91x/nrf9151/ns --sysbuild --extra-conf overlay-golioth-runtime-psk.confOnce the firmware has been flashed on the device, use the Serial Terminal app to set the PSK-ID and PSK in the Zephyr 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
These overlays can be combined to enable all the debug configurations at once.
west build -p -b thingy91x/nrf9151/ns --sysbuild --extra-conf overlay-serial-debug.conf --extra-conf overlay-golioth-logging.conf --extra-conf overlay-golioth-runtime-psk.confThis project uses GitHub Actions to automatically build the release firmware. Pull requests or pushes to the main branch of the repository will also trigger development builds. The firmware artifacts from these builds can be downloaded from the Build Firmware workflow page.
The Release workflow is used to automatically build the release firmware and upload the files into a draft release on GitHub. The draft release can be edited to include release notes before the release is published.
Important
The release workflow requires the release commit to be tagged with an annotated tag. This is required because Zephyr sets APP_BUILD_VERSION to the value of git describe --abbrev=12 --always, which does not support lightweight tags.
- Create a release branch (
git checkout -b release-v1.2.3) - Update VERSION to reflect the release version
- Update CHANGELOG.md with the release notes, version, and date
- Create a release commit (
git commit -m "Release v1.2.3") - Push the release branch to GitHub and create a pull request, e.g. titled "Release v1.2.3"
- Rebase and merge the pull request
- Tag the release commit (
git tag -s -a v1.2.3 -m "Release v1.2.3") - Push the release tag to the remote (
git push --tags) - The Release workflow will automatically build the firmware and create a draft release in Releases
- Copy the release notes from CHANGELOG.md into the draft release
- Publish the release on GitHub
- Follow the instructions in OTA Firmware Update to upload the release firmware to Golioth.
See the CONTRIBUTING.md file for project contribution guidelines.
See the LICENSE.md file for project licensing information.