Device Protocol (S3 Protocol)

This guide explains how your physical devices communicate with S3Suite. It is written for product managers and hardware engineers - no deep software knowledge required.

---

What is the S3 Protocol?

The S3 Protocol is the communication layer between your devices and the S3Suite platform. It handles:

• Identifying each device uniquely
• Sending health data from devices to the cloud
• Receiving commands (firmware updates, reboots, config changes) from the dashboard
• Provisioning new devices during manufacturing

Think of it as the language your devices speak to keep S3Suite informed about their status.

---

Device Identity

Every device in S3Suite has a unique identity made up of two parts:

Together, these form the device's identity in the system. This means:

• No two devices can have the same identity
• The identity ties the physical device to its digital record in S3Suite
• You can always trace a device back to its production lot

---

Provisioning

Provisioning is the process of giving a device its identity during manufacturing. Here is how it works:

1. You create a production lot in S3Suite (see Manufacturing Suite)
2. The lot gets a unique lot token
3. During manufacturing, the device firmware reads its own MAC address or IMEI
4. The device registers itself with S3Suite using the lot token + its hardware ID
5. S3Suite creates the device record and the device is now "provisioned"

From this point forward, the device is tracked in the system.

Note: Provisioning only happens once per device. After that, the device uses its established identity for all communication.

---

Health Reporting

Once provisioned, devices send health reports to S3Suite. These reports power the Health Dashboard in the Operations Suite.

What devices can report:

The device firmware decides how often to report and which metrics to include. S3Suite stores everything and makes it available in the dashboard.

---

Remote Commands

From the S3Suite dashboard, you can send commands to devices in the field:

• OTA firmware updates - Push a new firmware version to one device or an entire lot
• Reboot - Remotely restart a device
• Configuration changes - Update settings without a full firmware update

The device receives the command on its next check-in (or immediately in real-time mode). Command history is logged so you can verify what was sent and when.

---

Runtime Modes

Devices can communicate with S3Suite in three different modes, depending on your product's needs:

Periodic Mode

The device sends health data and checks for commands at a fixed interval (e.g., every 5 minutes, every hour). Best for battery-powered or low-bandwidth devices.

Piggyback Mode

The device sends data on demand - piggybacking on an existing communication event. For example, the device reports health data whenever it sends a normal data payload. Best for devices that already communicate regularly for other purposes.

MQTT Mode

The device maintains a real-time connection to S3Suite. Health data is sent instantly, and commands are received immediately. Best for always-on, always-connected devices where real-time monitoring matters.

---

Libraries (SDKs)

S3Suite provides pre-built libraries that make it easy to add the S3 Protocol to your firmware. You do not need to implement the protocol from scratch.

Available for:

Getting started with a library:

1. Go to your project in S3Suite
2. Open the Libraries tab
3. Download the library for your platform
4. Edit one configuration file with your project credentials (lot token, endpoint URL)
5. Add two lines to your firmware's main loop to initialize and run the protocol

That is it. The library handles identity, health reporting, command reception, and OTA updates.

Tip: Start with periodic mode during development. You can switch to MQTT later when you need real-time monitoring.

Note: For more on pushing firmware updates from the dashboard side, see Operations Suite - Firmware Updates.