Overview #
The system architecture’s scope covers both device and cloud, and an important concept is the vertical services covering these two domains in a consistent way.
These services are connected though the custom NB-IoT optimized protocol called ProtoCool.
The following figure gives an overview on this.
A service typically map a device functionality (sensor, actuator or anything) to an API endpoint in the cloud. These endpoints can be REST URLs or MQTT topics.
Device #
The device side has three tiers, and keeping them apart is the thing most often got wrong: the platform, modules, and products.
Platform #
The SDK every module is built on, and the protobuf API every module speaks. The SDK supplies the service loop, the message router, the BIST registry, the flash and configuration store, and the MIB transport. The API defines the message set. Neither knows anything about a particular device.
Modules #
A module is a generic, multifunctional building block: one MCU running the platform SDK, hosting one or more services, addressable on the MIB bus.
| Module | Role | Services it hosts |
|---|---|---|
gw |
Gateway. Carries the NB-IoT modem and the cloud link, and is the MIB controller the others answer to | access, lock, modem, battery, mag, autoclose, foat, emo |
dis |
Colour display | dis |
nfc |
NFC reader | nfc_uid_acl |
sun |
Sensor unit | ran, hut, imug, als |
A module is not specific to any product. dis is a display module that
knows how to draw scenes; it does not know it is in an access controller. Its
protobuf interface is the whole of what a product may ask of it.
Exactly one module in a device is the gateway: it holds the modem, terminates ProtoCool, and routes between the cloud and the other modules over the MIB bus or BLE. The others are peripherals.
Products #
A product is a customer-specific device built from a set of modules, offering a set of built-in services. The product is where the choice of modules, the enclosure, the electrical design and the supported service set are fixed; the modules themselves are unchanged.
So NRC1 and NRC2 are not “the firmware” — they are compositions. The same
gw firmware runs in both, and a service added to a module becomes available
to every product that includes it.
See Products for what each one is made of.
Cloud #
The cloud architecture is grouped in four mains part. APIs, ProtoCool, digital
twin and management. See the following figure for an illustration.
APIs (REST and MQTT) #
The main part of the API is the REST API. As an event-driven option there is also a MQTT broker where service messages are routed.
See API sections for details.
ProtoCool server #
Server implementation of ProtoCool
Digital Twin #
The digital twin consists of a mixed set of services, and have the following responsibilities:
- Expose service configuration in REST API and validate new configuration
- Keep the service configuration on the device up to date
- Persist last service messages and expose in REST API
- Publish service messages from device to MQTT topic
- Subscribe to MQTT messages and deliver to device service
Service messaging #
Service messages are defined as protobuf messages. These messages comes in three flavors:
- Configuration: Accessible in REST API and Digital Twin is responsible for keeping device service configuration in sync
- Status: Messages from device service that are cached by Device Twin and made accessible though REST API. Also published to MQTT broker.
- Message: Messages in both directions passed though MQTT broker
Management #
The management part of the cloud contains different functionalities. The following table gives an overview of these:
| Part | Description |
|---|---|
| Device | Device registry. Keeps track of device type, life cycle and production data |
| SIM | Keep track of all SIMs and synchronize against external telco API |
| Key | Security key storage. Used for device communication security key. Can be set from manufacturer |
| Firmware | Firmware release registry. To provide production and FOTA services with firmware images |
| Auth | Authentication/authorization for API endpoints |
Data model #
Device:
| Field | Type | Description |
|---|---|---|
| dev_id | string | Unique device id |
| created | time | Time of device object creation |
| updated | time | Time of last device object update |
| state | string | Life cycle state |
| actor | string | Optional update actor. Used to track who is doing updates |
| type | string | Device type |
| variant | string | Non-functional device variants within same type |
Production data:
| Field | Type | Description |
|---|---|---|
| dev_id | string | Unique device id |
| updated | time | Time of last production object update |
| manuf | string | Manufacturer |
| firmwares | key/value table | Firmware version used in production |
| modem_imei | string | Modem IMEI number |
| modem_meta | object | Collected information about modem |
| packaging | key/value table | Packaging assignment |
| meta | object | Other information from production |
| test_results | object | Recorded test results |
SIM:
| Field | Type | Description |
|---|---|---|
| iccid | string | Unique SIM ICCID number |
| created | time | Time of sim object creation |
| updated | time | Time of last sim object update |
| dev_id | string | Assigned to device id |
| fixed | bool | Fixed (non-removable) SIM |
| imsi | string | SIM IMSI number |
| imei | string | IMEI number from telco |
| state | string | Sync state |
| status_req | string | Requested status |
| status | string | Status (From telco) |
| error | string | Telco sync error |
| telco_updated | time | Telco sync update time |
| msisdn | string | MSISDN number from telco |
| last_session | time | Last session time registered by telco |
| country | string | Telco registered country |
| meta | object | Any other information retrieved from telco |
Services #
Services are vertical building blocks.
ProtoCool #
Proprietary message protocol optimized for NB-IoT with the following features:
- Bundle multiple messages in same NB-IoT packet
- Uplink and downlink message delivery guarantee and de-duplication