HOME » RESOURCES » TOOLS » LoRa Basics Station » The CUPS Protocol

LoRa Basics Station

The CUPS Protocol

Station periodically queries CUPS for updates. The protocol is HTTP/REST using the client/server authentication methods described in Section Credentials. With each query, Station provides information about its current state and gets back a binary blob containing updates for its LNS and CUPS credentials as well as a generic data segment with arbitrary updates.

The format of the generic data segment is platform-dependent. Station just executes this file after download, which usually is a self-extracting shell script but also MAY be a binary executable.

CUPS Protocol


The URI of the CUPS update end point is constructed from the contents of the file cups.uri (or one of its fallback alternatives as described in Section Credentials). The path /update-info is added and an HTTP POST request is submitted with the body containing 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.

Both cupsUri and tcUri fields are the contents of credentials 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 Station, the gateway model, and the version of the package. The package version may contain information about the state of the underlying system and its configuration.

The keys field finally contains an array of CRC32 checksums for each of the signing keys installed on the firmware where 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 of the follwing 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
2 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 MUST be encoded in little endian. If any of the length fields is zero, there is no update for this particular component. If CUPS returns a blob with all length fields zero, there is no update pending.

The credentials blob is a concatenation of trust/cert/key, which is able to encode both client authentication using X509 certificates and client authentication 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 gateway;
  • key 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 the response would contain four zero octets for this part;
  • The key is an authorization token which MUST be added as such to the subsequent requests to CUPS as part of the headers for the HTTP POST.

Station unpacks non-empty fields into their respective local credential files. If generic update data is present and the signature verifies, the update gets saved into a file named update.bin and executed once downloaded successfully.

This update executable/script MAY replace the station binary, update configuration file, update the underlying system, and finally restarts the station process or reboots the gateway.