SDK Architecture – iotconnect

SDK and Firmware Architecture

Understanding the clear separation between Device Firmware/Application and the /IOTCONNECT™ SDK – what each layer is responsible for, how they interact, and why this separation enables modular, maintainable IoT solutions.

Architecture Overview

The /IOTCONNECT™ architecture cleanly separates your device into three layers. The SDK sits between your firmware and the cloud, handling all communication complexity so your code stays focused on hardware and business logic.

Key Takeaway: Your firmware calls simple SDK APIs (connect, send_telemetry, on_command). The SDK handles all MQTT, authentication, reconnection, and protocol formatting automatically. When using the SDK APIs, application code does not need to directly implement MQTT or cloud protocol handling.

SDK Integration and Data Flow

This diagram shows the complete developer workflow — from initializing the SDK to sending telemetry and receiving commands:

End-to-End Communication Flow

Data flows bidirectionally between device and cloud through the SDK layer:

Responsibility Separation

Firmware / Application	/IOTCONNECT™ SDK	/IOTCONNECT™ Cloud
Hardware interaction (GPIO, peripherals)	Cloud communication (MQTT)	Device management
Sensor reading and data collection	Authentication and identity	Telemetry ingestion and storage
Actuator and motor control	Telemetry publishing	Command dispatch
Business logic and decision making	Command reception and routing	Rules and event processing
Device-specific processing	Connection/reconnection handling	Dashboards and visualization
Application state management	Message serialization and formatting	OTA management
Local data filtering/aggregation	Retry and delivery guarantees	Data analytics
Hardware drivers	/IOTCONNECT™ protocol abstraction	Device configuration

The device firmware remains responsible for hardware and application-specific functionality, while the /IOTCONNECT™ SDK provides a standardized communication layer that connects the device to the platform.

Why This Separation Matters

Modular Architecture: Firmware and cloud communication are separated into independent layers. The separation reduces coupling and allows many cloud communication changes to be isolated from application logic(Changes in one do not break the other).

Hardware Independence: The SDK communication layer can be reused across different device hardware without rewriting cloud logic.

Easier Maintenance: Cloud protocol changes are handled within the SDK without requiring changes to your application logic.

Faster Development: Developers focus on hardware and business logic while the SDK handles all /IOTCONNECT™ communication complexity.

Consistent Communication: All devices use a standardized interface for telemetry, commands, and configuration.

Reusability: The same SDK architecture integrates into multiple device types and product variants with minimal adaptation.

SDK Architecture

Understand how the /IOTCONNECT™ SDK connects devices to the cloud — from discovery and authentication through MQTT connection to bidirectional data communication.

SDK connection workflow

The SDK follows a multi-step workflow to establish a secure connection between your device and /IOTCONNECT™:

Step 1 — Discovery: SDK calls the Discovery API with your CPID and Environment to retrieve the base URL and connection parameters for your account.

Step 2 — Identity Sync: SDK calls the Agent Sync endpoint with your Device Unique ID to fetch device-specific configuration: attributes, commands, authentication method, protocol settings, and MQTT topic structure.

Step 3 — Authentication: Based on the auth type (X.509 certificate or symmetric key), the SDK prepares credentials and establishes a TLS-encrypted connection to the MQTT broker.

Step 4 — MQTT Connection: SDK connects to the Cloud MQTT broker, subscribes to the C2D (cloud-to-device) topic for receiving commands, and publishes telemetry on the D2C (device-to-cloud) topic.

Step 5 — Data Exchange: Device publishes telemetry and receives commands through the established MQTT connection. The SDK handles message formatting, acknowledgments, and reconnection.

Communication protocols

The SDK supports two primary communication protocols:

MQTT (Primary): Lightweight publish-subscribe protocol over TLS. Persistent connection with QoS 1 for reliable delivery. Used for real-time telemetry streaming and instant command reception. Port 8883.

HTTPS (Fallback): Request-response protocol for environments where MQTT is blocked by firewalls. Higher latency but works through corporate proxies. Used for discovery and sync API calls.

All communication is encrypted with TLS 1.2+ ensuring data confidentiality and integrity in transit.

Message types

The SDK handles several message types in the /IOTCONNECT™ 2.1 protocol:

Telemetry (D2C): Device-to-cloud sensor data. JSON payload with attribute values matching the template definition.

Commands (C2D): Cloud-to-device messages for remote control. Contains command text, optional parameters, and acknowledgment ID.

Twin / Shadow: Desired and reported property synchronization between cloud and device for configuration management.

OTA Notification: Firmware update availability notification with download URL, version info, and update instructions.

Acknowledgment: Device confirms command receipt or reports execution status (success / failure) back to the platform.

Fault / Error: Device reports error conditions, validation failures, or connectivity issues to the platform for diagnostics.

SDK layers

The SDK is structured in layers for modularity:

Application Layer: Your device code — business logic, sensor reading, actuator control. Calls SDK functions.

SDK Client Layer: High-level API (connect, send_telemetry, on_command). Handles message formatting and protocol translation.

Transport Layer: MQTT / HTTPS client implementation. Manages connection lifecycle, reconnection, and QoS.

Security Layer: TLS, certificate management, key storage. Handles authentication handshake.

Platform Layer: OS-specific abstractions (file system, network, timers). Enables portability across hardware.

ⓘ NOTE

The SDK uses the /IOTCONNECT™ Message Protocol 2.1. SDK libraries are available for C, Python, C#, Node.js, Java, Android, and iOS.