Tools
LoRa Basics™ Station 2.0.5 documentation
The CUPS Protocol¶
The LoRa Basics™ Station periodically queries the CUPS server for updates. The protocol is HTTP/REST, using the client/server authentication methods described in Credentials. With each query, the Station provides information about its current state and receives a binary blob containing updates for its LNS and CUPS credentials, along with a generic data segment with arbitrary updates.
The format of the generic data segment is platform-dependent. The Station simply executes this file after downloading it. Usually it is a self-extracting shell script. However, it may also be a binary executable.

HTTP POST Request¶
The URI of the CUPS update end point is constructed from the contents of the cups.uri
file (or one of its fallback alternatives as described in Credentials). The path /update-info
is added and an HTTP POST request is submitted with the body. The HTTP POST request contains the following JSON object:
{
"router" : ID6,
"cupsUri" : "URI",
"tcUri" : "URI",
"cupsCredCrc" : INT,
"tcCredCrc" : INT,
"station" : STRING,
"model" : STRING,
"package" : STRING,
"keys" : [INT]
}
The router
field is the ID6 representation of the gateway’s identity.
The values of the cupsUri
and tcUri
fields are the contents of the credential files cups.uri
and tc.uri
, respectively.
The cupsCredCrc
and tcCredCrc
fields are CRC32 checksums calculated over the concatenated credentials files cups.{trust,cert,key}
and tc.{trust,cert,key}
.
The station
, model
, and package
fields describe the current version of the Station, the gateway model and the package version. The package version may contain information about the state of the underlying system and its configuration.
The keys
field contains an array of CRC32 checksums for each of the signing keys installed on the firmware where the Station is running. The response from the server will provide a signed update, if available, with a signature matching one of these signing keys.
HTTP POST Response¶
The CUPS server shall respond with a binary blob in the following format:
Bytes |
Field |
Description |
---|---|---|
1 |
cupsUriLen |
Length of CUPS URI (cun) |
cun |
cupsUri |
CUPS URI (cups.uri) |
1 |
tcUriLen |
Length of LNS URI (tun) |
tun |
tcUri |
LNS URI (tc.uri) |
2 |
cupsCredLen |
Length of CUPS credentials (ccn) |
ccn |
cupsCred |
Credentials blob |
2 |
tcCredLen |
Length of LNS credentials (tcn) |
tcn |
tcCred |
Credentials blob |
4 |
sigLen |
Length of signature for update blob |
4 |
keyCRC |
CRC of the key used for the signature |
sig |
sig |
Signature over the update blob |
4 |
updLen |
Length of generic update data (udn) |
udn |
updData |
Generic update data blob |
The length fields shall be encoded in little endian. If any of the length fields are zero, there is no update for that particular component. If CUPS returns a blob where all length fields are zero, there is no update pending.
The credentials blob is a concatenation of trust/cert/key
, which is able to encode client authentication, using X509 certificates and using tokens.
For client authentication using X509 certificates, all credentials are encoded in DER format:
trust
is the certificate of the trusted certificate authority (CA)cert
is the personal certificate for the gatewaykey
is the personal private key for the gateway
For token-based authentication, trust
is the same DER as above, however:
the private
cert
is not required, and, if absent, the response will contain four “zero” octets for this partThe
key
is an authorization token which must be added to the subsequent requests to CUPS as part of the headers for the HTTP POST request
The Station unpacks non-empty fields into their respective local credential files. If generic update data is present and the signature is verified, the update gets saved into a file named update.bin
and is executed once downloaded successfully.
This executable/script may replace the Station binary. It may then update the configuration file and the underlying system before restarting the Station process or rebooting the gateway.
LoRa Basics™ Station 2.0.5 documentation
ADDITIONAL RESOURCES - CODE
ADDITIONAL RESOURCES - VIDEOS
- Part 1: An Introduction
- Part 2: System Overview
- Part 3: Key Features
- Part 4: Understanding the Building Blocks
- Part 5: Understanding the LNS Protocol
- Part 6: Understanding the CUPS Protocol
- Part 7: Understanding Security
- Part 8: Understanding the Simulation Environment
- Part 9: Live Example Walk-Through