Preset

SenseCAP Cloud

SenseCAP S21xx nodes already report to the SenseCAP cloud through a SenseCAP M2 gateway; nothing on the radio side changes. A bridge container pulls history and live data from the cloud and publishes them as local Home Assistant entities.

Host: A Linux host with Docker for Home Assistant, the MQTT broker and the bridge.
Account: A SenseCAP Portal account and an API key pair.
Known limits: Two cloud MQTT hostnames are in circulation and the deployment offers both; after the first deployment, check the bridge log to confirm it connected.

Deploy Home Assistant and the Broker

Starts Home Assistant and a Mosquitto broker on one host. Skip this if you already run both and the bridge can reach your existing broker.

Prerequisites

At least 8 GB free disk on the host.
Ports 8123 and 1883 free, or different ports set in this step's inputs.
A broker password, written down; the bridge step asks for the same value.

Troubleshooting

Symptom	Fix
Port 8123 or 1883 already in use	Stop the existing Home Assistant or Mosquitto, or set different ports in this step's inputs
Mosquitto restarts with `Unable to open pwfile`	Make the password file owned by the `mosquitto` user
Home Assistant never answers on 8123	First start takes a few minutes; run `docker logs agri-env-homeassistant`
Deploy cannot connect	Confirm SSH is reachable and the username is right (`pi` on Raspberry Pi OS, `recomputer` on reComputer)

Deployment method

Deploy over SSH to a Linux host with Docker; amd64 and arm64 both work.

What you will be asked for(filled in the SenseCraft Solution app)

Host Address*
The machine that will run Home Assistant and the broker
SSH Username*default pi
Common defaults: pi (Raspberry Pi OS), recomputer (Seeed reComputer), ubuntu.
SSH Password*
Time Zone*default Asia/Shanghai
IANA name — it decides how timestamps read on the dashboard
Home Assistant Port*default 8123
Change this if 8123 is already taken on this host
MQTT Port*default 1883
MQTT Username*default agrienv
Used by Home Assistant's MQTT integration and by the bridge; the broker refuses anonymous clients
MQTT Password*
Write it down — the next step asks for the same value

Deploy the Cloud Bridge

Deploys the bridge that reads the SenseCAP cloud. It lists the devices on your account, backfills their history, then subscribes to live data.

Prerequisites

A SenseCAP API key pair (Access ID and Access Key) from the SenseCAP Portal under Security → Access API Keys.
The broker address, port, username and password from step 1. If the bridge runs on a different machine, use the LAN IP rather than 127.0.0.1.
A backfill window: up to three months; a longer window means more requests.

Troubleshooting

Symptom	Fix
Bridge log shows a DNS failure for the cloud host	Redeploy with the other option in the MQTT host selector
Bridge log shows an authentication failure	Check the Access ID and Access Key pair, and that the key has not been revoked in the Portal
Devices appear but no values	Backfill writes only the latest value per entity; with hourly reporting, the first live update can take up to an hour
`no such image` on deploy	With a self-built `BRIDGE_IMAGE`, build it locally first and re-run
Nothing reaches the broker	When the bridge is not on the Home Assistant host, set the broker address to the LAN IP

Deployment method

Deploy the bridge over SSH to a host with Docker.

What you will be asked for(filled in the SenseCraft Solution app)

Bridge Host Address*
Where the bridge container runs — usually the same machine as Home Assistant
SSH Username*default pi
SSH Password*
Time Zone*default Asia/Shanghai
MQTT Broker Address*default 127.0.0.1
The broker deployed with Home Assistant. Use the host's LAN address, not 127.0.0.1, when the bridge runs on a different machine.
MQTT Port*default 1883
MQTT Username*default agrienv
MQTT Password*
The same value you set on the Home Assistant step
SenseCAP Access ID*
From the SenseCAP Portal, Security → Access API Keys
SenseCAP Access Key*
The secret half of the API key pair. It is written only to a mode-600 .env file on the target host.
SenseCAP Cloud MQTT Host*default sensecap-openstream.seeed.cc
2 options
- · sensecap-openstream.seeed.cc — used by a shipping Seeed solution
- · openstream.api.sensecap.seeed.cc — appears in documentation
Two hostnames are in circulation and neither is confirmed. Try the default first; if the bridge log shows a DNS or authentication failure, redeploy with the other.
Backfill Window*default 1
3 options
- · None — live data only
- · 1 month
- · 3 months — the API maximum
How far back to pull history on first start. The OpenAPI reaches back three months at most and serves one month per request, so a longer window means more requests.
Offline Threshold (seconds)*default 7200
No uplink for this long marks the node offline in Home Assistant. Default is two S210x reporting cycles plus margin — raise it if your nodes report less often than hourly.

Check the Data in Home Assistant

Open Home Assistant and confirm the nodes arrived as devices with entities.

Troubleshooting

Symptom	Fix
MQTT integration connects but no devices appear	Run `docker logs agri-env-bridge-cloud` and confirm the cloud connection line is there
Entities appear as `unavailable` right away	Confirm the nodes are reporting and the offline threshold is not shorter than their interval
An entity has no unit	Add its `measurementId` to `assets/config/measurements.yaml`
Old entity ids keep coming back	Clear the broker's retained messages and Home Assistant's entity registry together

After Deployment

Every node on the account is a Home Assistant device named SenseCAP <DevEUI>, with one entity per measurement.

Quick verification

Sign in to Home Assistant and complete the onboarding wizard on a fresh install.
Settings → Devices & Services → Add integration → MQTT, with the host running the stack, port 1883, and the username and password from step 1. Skip if MQTT is already configured.
Open the MQTT integration, open a device, and check its entities carry units (°C, %, dS/m).
Import the dashboard: Overview → three-dot menu → Edit dashboard → three-dot menu → Raw configuration editor, paste assets/homeassistant/agri_env_dashboard.yaml, and replace the example DevEUIs with your own.
Import the threshold alerts: merge assets/homeassistant/automations.yaml into Home Assistant's automations.yaml and reload automations. The shipped for: durations are zero; adjust thresholds and durations before field use so a single noisy reading does not trigger an alert.

Next steps

Set the offline threshold to match the nodes' reporting interval. The default assumes hourly reporting; nodes reporting every six hours are marked offline between uplinks.
Put the entities you act on in a separate view.

Preset

Custom Ops Dashboard

A dedicated ops console that renders the normalized data from the agri-env bridge as a purpose-built dashboard — a focused alternative view alongside Home Assistant. One container, no cloud account: it subscribes to the bridge's MQTT output and displays what the bridge decodes.

Runs beside: an ingest preset (SenseCAP Cloud, Local Network Server, or the bridge alone) — this dashboard reads the bridge's normalized state topics, it does not decode uplinks itself.
Host: A Linux host with Docker for the dashboard container. The reComputer R1000 Series works as a kiosk.
Broker: The MQTT broker the agri-env bridge publishes to, reachable from the host, with its username and password if it has any.
Known limits: The dashboard is receive-only and reads the bridge's normalized state topics; it does not use the Home Assistant entity naming from the other presets.
Bare-metal option: to run the dashboard directly on a reComputer with a kiosk display instead of Docker, see assets/custom_dashboard/MISSION-PACK.md.

Deploy the Ops Dashboard

Deploys the dashboard bridge, subscribed to the agri-env bridge's normalized MQTT output. It serves the ops console over HTTP and pushes live updates over WebSocket.

Prerequisites

An ingest preset (SenseCAP Cloud, Local Network Server, or the agri-env bridge alone) already running and publishing to your broker — this dashboard reads its output.
At least 2 GB free disk on the host.
The HTTP and WebSocket ports free (defaults 8000 and 8765; on a reComputer R1000, port 8000 is taken, so use 8001).
The MQTT broker's address, port, and credentials if it has any, plus the topic prefix if your relay uses one.

Troubleshooting

Symptom	Fix
Dashboard log shows an MQTT authentication failure	Check the broker username and password, and that the account may read the sensor topic
Dashboard log shows a connection refused or timeout	Check the broker address and port, and that the broker is reachable from this host (use the LAN IP, not `127.0.0.1`, if they are on different machines)
Page loads but every source shows "no data"	Sensors that report hourly can take up to an hour to populate; check `/admin` for each source's data health
`no such image` on deploy	With a self-built `OPS_DASHBOARD_IMAGE`, build it locally first and re-run
Port already in use	Stop whatever holds the port, or set a different HTTP port in this step's inputs (8001 on a reComputer R1000)

Deployment method

Deploy over SSH to a Linux host with Docker; amd64 and arm64 both work.

What you will be asked for(filled in the SenseCraft Solution app)

Time Zone*default Asia/Shanghai
Dashboard HTTP Port*default 8000
The port the ops console is served on. On a reComputer R1000, 8000 is taken by another service, so use 8001.
Live Updates WebSocket Port*default 8765
MQTT Broker Address*
The broker your sensor gateway already publishes to. Use a LAN IP or hostname reachable from this host.
MQTT Port*default 1883
MQTT over TLS*default 0
2 options
- · No — plain TCP (1883)
- · Yes — TLS (8883)
MQTT Username
Leave empty if your broker allows anonymous reads
MQTT Password
Written only to a mode-600 .env file on the target host
MQTT Topic Prefix
Prepended to the sensor topic, if your relay uses one. Leave empty for none.
Sensor State Topic*default agri_env/+/+/state
The normalized state topic the agri-env bridge publishes. One of the three ingest presets (or the bridge alone) must be running — this dashboard reads its output.

Open the Ops Dashboard

Open the ops console and confirm your sensors appear.

Troubleshooting

Symptom	Fix
Page does not load	Confirm the container is running (`docker ps`) and the HTTP port is the one you set
MQTT shows disconnected	Recheck the broker address, port, and credentials from step 1
Sources stay on "no data"	Confirm the sensors are reporting and the topic / prefix match what your relay publishes

After Deployment

The dashboard subscribes to your broker and renders every reading it decodes, with history kept on the host.

Quick verification

Open http://<host>:<http_port>/ops. The page loads with the ops console.
Confirm the MQTT indicator shows connected (top of the page). If it shows disconnected, recheck the broker settings from step 1.
Wait for the first uplink; sensors that report hourly can take up to an hour. Each source's live / delayed / silent status is on /admin.
Optional kiosk: on a reComputer, open the same URL in the device's browser and leave it full-screen.

Next steps

Set the broker to require authentication if it does not already, and keep the dashboard host on the same trusted network as the broker.
To run the dashboard on a different port, redeploy step 1 with a different HTTP port and open the new URL.

Preset

Local Network Server

Self-hosted LoRaWAN network server (ChirpStack or The Things Stack) for complete off-grid deployment. Use the built-in ChirpStack on the SenseCAP M2 gateway, or run ChirpStack or The Things Stack in Docker on a reComputer R12 Series gateway; data from the SenseCAP S21xx nodes never leaves the local network.

Host: A Linux host with Docker for Home Assistant, the MQTT broker and the bridge.
Nodes: Each node's DevEUI, JoinEUI and AppKey, with the node band matching the gateway.
Known limits: Local mode takes the M2 off the SenseCAP cloud; whether your firmware can report to both at once has to be confirmed on the unit. Check available memory on the gateway host before starting The Things Stack.

Deploy Home Assistant and the Broker

Starts Home Assistant and a Mosquitto broker on one host. Skip this if you already run both and the bridge can reach your existing broker.

Prerequisites

At least 8 GB free disk on the host.
Ports 8123 and 1883 free, or different ports set in this step's inputs.
A broker password, written down; subsequent steps ask for the same value.

Troubleshooting

Symptom	Fix
Port 8123 or 1883 already in use	Stop what holds it, or set different ports in this step's inputs
Mosquitto restarts with `Unable to open pwfile`	Make the password file owned by the `mosquitto` user
Home Assistant never answers on 8123	First start takes a few minutes; run `docker logs agri-env-homeassistant`
Deploy cannot connect	Check SSH and the username for your OS image

Deployment method

Deploy over SSH to a Linux host with Docker.

What you will be asked for(filled in the SenseCraft Solution app)

Host Address*
The machine that will run Home Assistant and the broker
SSH Username*default pi
Common defaults: pi (Raspberry Pi OS), recomputer (Seeed reComputer), ubuntu.
SSH Password*
Time Zone*default Asia/Shanghai
IANA name — it decides how timestamps read on the dashboard
Home Assistant Port*default 8123
Change this if 8123 is already taken on this host
MQTT Port*default 1883
MQTT Username*default agrienv
Used by Home Assistant's MQTT integration and by the bridge; the broker refuses anonymous clients
MQTT Password*
Write it down — the next step asks for the same value

Switch the M2 to Local Network Server

Take the M2 off the cloud and turn on its built-in ChirpStack. If using an R12 gateway, skip this step.

Prerequisites

The M2's LAN IP and web interface credentials.
The model, band and firmware version from its status page, written down. The menu path is LoRa → LoRa Network; if yours differs, check the firmware version first.
An MQTT host, port, username and password for the built-in network server to publish to; the bridge subscribes to that broker.

Troubleshooting

Symptom	Fix
Uplinks stop appearing in the Portal	Expected in local mode
The built-in ChirpStack has no application	Create the tenant, application and device profile before joining nodes in step 7
Uplinks arrive with no `object`	Paste the SenseCAP decoder for your node series into the device profile's codec

Bring Up the reComputer R12 Gateway Radio (ChirpStack)

Perform this step when using a reComputer R12 Series gateway with ChirpStack: connect the antenna, confirm the SPI device, and point the packet forwarder to the local ChirpStack bridge. If using an M2 or an R12 with The Things Stack, skip this step.

Wiring

Connect the LoRa antenna to its SMA jack before applying power; transmitting without an antenna can damage the radio.
Confirm /dev/spidev0.0 is present; if not, enable SPI and reboot.
Look up the reset, power-enable and SX1261 pin numbers in the R12 product wiki and write them down.
The regional band the gateway was ordered on must match the chosen frequency plan and the nodes' band.

Troubleshooting

Symptom	Fix
Forwarder exits without printing an EUI	Confirm SPI is enabled, then check the reset pin
Gateway's `Last seen` never updates	Check that the firewall passes UDP 1700
Concentratord starts but the gateway bridge sees nothing	Switch to the UDP packet forwarder to get uplinks flowing, then check whether the concentratord ZMQ endpoints are reachable from inside the container

Bring Up the reComputer R12 Gateway Radio (The Things Stack)

Perform this step when using a reComputer R12 Series gateway with The Things Stack: connect the antenna, confirm the SPI device, and run a packet forwarder pointed at The Things Stack. If using an M2 or an R12 with ChirpStack, skip this step.

Wiring

Connect the LoRa antenna to its SMA jack before applying power; transmitting without an antenna can damage the radio.
Confirm /dev/spidev0.0 is present; if not, enable SPI and reboot.
Look up the reset, power-enable and SX1261 pin numbers in the R12 product wiki and write them down for the packet forwarder configuration.
Check that the regional band the gateway was ordered on matches the nodes' band; the band cannot be changed in software.

Troubleshooting

Symptom	Fix
Forwarder exits without printing an EUI	Confirm `/dev/spidev0.0` exists, then check the reset pin
Gateway stays disconnected in the Console	Check that the firewall passes UDP 1700 to the stack host
Concentrator starts but no uplinks	Check that the gateway band, frequency plan and node band match

Deploy ChirpStack and the Bridge

Choose m2 to start only the bridge, or local to start ChirpStack on this host as well. If using The Things Stack (step 6), skip this step.

Prerequisites

On the m2 route: the M2's broker address, port, username and password from step 2.
On the local route: at least 8 GB free disk, and a frequency plan matching the gateway and the nodes.
The broker address, port, username and password from step 1.
The application ID; + subscribes to every application on that broker.

Troubleshooting

Symptom	Fix
Bridge log shows no `ChirpStack MQTT connected`	On the `m2` route, re-check the address and credentials on the gateway's LoRa Network page; on the `local` route, run `docker compose --profile local-lns ps`
ChirpStack services did not start on the `local` route	Confirm `lns_mode` is `local` and re-run this step
Web interface on 8080 is unreachable	Only the `local` route has it; on the `m2` route, use the gateway's web interface
`no such image` on deploy	With a self-built `BRIDGE_IMAGE`, build it locally first and re-run

Deployment method

Deploy over SSH to the host that will run the bridge.

What you will be asked for(filled in the SenseCraft Solution app)

Host Address*
The machine that runs the bridge — the R1000 on the first route, or any Linux host on the M2 route
SSH Username*default pi
SSH Password*
Time Zone*default Asia/Shanghai
Where the Network Server Runs*default m2
2 options
- · On the M2 gateway (built-in ChirpStack)
- · On the R12 gateway (ChirpStack + built-in concentrator)
Pick `m2` if the gateway runs its own network server — nothing but the bridge starts here. Pick `local` to run ChirpStack on a reComputer R12 Series gateway.
Frequency Plan*default eu868
5 options
- · EU868
- · US915
- · AS923
- · AU915
- · CN470
Only used on the `local` route. It must match both the concentrator's band and the nodes' band — a mismatch looks exactly like a gateway that hears nothing.
Network Server Broker Address*default chirpstack-mosquitto
On the M2 route, the M2's own address. On the `local` route leave the default — it is the broker inside this compose project.
Network Server Broker Port*default 1883
Network Server Broker Username
Leave empty on the `local` route. On the M2 route use the credentials shown on the gateway's LoRa Network page.
Network Server Broker Password
Application ID*default +
The ChirpStack application UUID the bridge subscribes to. `+` subscribes to every application on that broker, which is the simplest thing that works for a single-tenant deployment.
Home Assistant Broker Address*
The Mosquitto deployed with Home Assistant — where the bridge publishes entities
Home Assistant Broker Port*default 1883
Home Assistant Broker Username*default agrienv
Home Assistant Broker Password*
Offline Threshold (seconds)*default 7200
No uplink for this long marks the node offline in Home Assistant

Deploy The Things Stack and the Bridge

If choosing The Things Stack, starts The Things Stack (with Postgres and Redis), initialises it, and starts the bridge. Allow 15–30 min for the first run. If ChirpStack was deployed in step 5, skip this step.

Prerequisites

At least 10 GB free disk.
The host's LAN IP (not 127.0.0.1, or other machines cannot sign in to the Console).
Ports 1885 (Console) and 1700/udp (packet forwarder) free.
The broker address, port, username and password from step 1.
The application ID and API key are created in step 8: deploy this step, create them in the Console and fill them in, update TTN_MQTT_PASSWORD in .env, and run docker compose up -d bridge to recreate the bridge container.

Troubleshooting

Symptom	Fix
`is-db migrate` fails	Postgres was not ready; re-run the initialisation
Console loads but sign-in loops	Redeploy with the host's LAN IP
Bridge log shows no `TTS MQTT connected`	Create the application and API key in step 8, then update .env and recreate the bridge
Stack container is killed on start	Check the host's available memory

Deployment method

Deploy to the gateway host over SSH.

What you will be asked for(filled in the SenseCraft Solution app)

Gateway Host Address*
The machine running the concentrator and this stack. It must be an address the browser and the packet forwarder can both reach — not 127.0.0.1.
SSH Username*default pi
SSH Password*
Time Zone*default Asia/Shanghai
Console Admin Email*
The address the admin account is created with. It is not sent anywhere — the stack has no mail server configured.
Console Admin Password*
Used to sign in to the Console on port 1885
Home Assistant Broker Address*
The Mosquitto deployed with Home Assistant — where the bridge publishes entities
Home Assistant Broker Port*default 1883
Home Assistant Broker Username*default agrienv
Home Assistant Broker Password*
Application ID*default agri-env
The application you will create in the Console. The bridge subscribes to its uplinks.
Application MQTT Username*
Form: {application-id}@{tenant-id}. On a self-hosted Open Source stack the tenant is usually the same string for every application.
Application API Key
An API key with rights to read application traffic. Created in the Console under Integrations → MQTT, and shown only once. Keep the default placeholder on first deployment, then create and backfill it once Console is running.
Offline Threshold (seconds)*default 7200
No uplink for this long marks the node offline in Home Assistant

Join the Sensors to ChirpStack

Prerequisites

A device profile created in ChirpStack matching the nodes, configured with the SenseCAP decoder for their series (the upstream repository has no LICENSE file and its licensing is unconfirmed).
Each node's DevEUI, JoinEUI and AppKey, printed on the node or readable with the SenseCAP Mate app over NFC.
The gateway is visible in ChirpStack and shows online/connected.

Troubleshooting

Symptom	Fix
ChirpStack rejects the DevEUI	The DevEUI already exists in another tenant, common when moving nodes from another network
Join request but no accept	Check the keys and regional parameters
No join request at all	Check the gateway status first to confirm it hears the node
Uplinks arrive with no decoded data (`object.messages`)	Set the codec for the node series in the device profile

Join the Sensors to The Things Stack

Create the application, install the payload formatter, and join the nodes. After generating an API key in the Console, backfill it in the deployment directory and recreate the bridge container:

sed -i 's/^TTN_MQTT_PASSWORD=.*/TTN_MQTT_PASSWORD="<generated_api_key>"/' .env
docker compose up -d bridge

Prerequisites

The gateway shows as Connected in the Console.
Each node's DevEUI, JoinEUI and AppKey, printed on the node or readable with the SenseCAP Mate app over NFC.
The SenseCAP decoder for your node series (upstream repository); without it no entity appears. That repository has no LICENSE file and its licensing is unconfirmed.

Troubleshooting

Symptom	Fix
Join request but no join accept	Check the keys and regional parameters
No join request at all	Check the gateway status first to confirm it hears the node
Uplinks arrive with no `decoded_payload`	Install the payload formatter on this application
`decoded_payload` present but no `messages` array	Use the decoder for your node series

Check the Data in Home Assistant

Open Home Assistant and confirm the nodes arrived; for an offline deployment, also confirm it keeps working with the internet cut.

Next Steps

Engineering Wiki

Troubleshooting

Symptom	Fix
Devices appear, entities are `unavailable`	Check the reporting interval against the offline threshold
Entities stop updating when the WAN is cut	Check the bridge log and the gateway's network page for whatever still reaches outward
An entity has no unit	Add its `measurementId` to `assets/config/measurements.yaml`
Old entity ids keep coming back	Clear the broker's retained messages and the entity registry together

After Deployment

Data from node to dashboard stays on the local network and does not depend on a cloud account. Each joined node is a Home Assistant device named SenseCAP <DevEUI>, with one entity per measurement.

Quick verification

Sign in to Home Assistant and complete onboarding on a fresh install.
Settings → Devices & Services → Add integration → MQTT, pointed at the broker from step 1.
Open the MQTT integration; each node is a device named SenseCAP <DevEUI>. Open one and check the entities carry units.
Paste assets/homeassistant/agri_env_dashboard.yaml into the Lovelace raw configuration editor and replace the example DevEUIs with your own.
Merge assets/homeassistant/automations.yaml into Home Assistant's automations.yaml, reload automations, and set the thresholds and for: durations for your site.

Offline acceptance

Run this once the dashboard works:

Note the current value and last-updated time of one entity per node.
Cut the site's WAN (unplug the uplink or block outbound traffic at the firewall) and leave the local network up.
Wait for at least two reporting intervals; every entity should keep updating. If any stop, check the bridge log and the gateway's page.
Restart the gateway and record the time from power-on to the first uplink in Home Assistant as the site's recovery time.
Restore the WAN; the data is unaffected.

Next steps

Set the offline threshold to match the nodes' reporting interval.
For an air-gapped site, pull the container images while the host still has a network, or load them from an archive; they cannot be pulled with the WAN cut.

Agricultural Environment Monitoring — Deployment Guide

Need help choosing hardware, or ready to deploy?

SenseCAP Cloud

Deploy Home Assistant and the Broker

Deploy the Cloud Bridge

Check the Data in Home Assistant

Quick verification

Next steps

Custom Ops Dashboard

Deploy the Ops Dashboard

Open the Ops Dashboard

Quick verification

Next steps

Local Network Server

Deploy Home Assistant and the Broker

Switch the M2 to Local Network Server

Bring Up the reComputer R12 Gateway Radio (ChirpStack)

Bring Up the reComputer R12 Gateway Radio (The Things Stack)

Deploy ChirpStack and the Bridge

Deploy The Things Stack and the Bridge

Join the Sensors to ChirpStack

Join the Sensors to The Things Stack

Check the Data in Home Assistant

Next Steps

Quick verification

Offline acceptance

Next steps