SDK and Firmware Architecture

The /IOTCONNECT™ SDK provides a clear separation between your device firmware/application logic and cloud communication. This page documents the architecture layers, how the SDK abstracts all cloud complexity, and what each layer is responsible for — enabling developers to focus on hardware and business logic without touching MQTT, TLS, or protocol details.

Three-Layer Architecture

The /IOTCONNECT™ device architecture consists of three cleanly separated layers:

Layer 1 — Device Firmware / Application: Your code. Reads sensors, controls actuators, implements business logic, manages hardware. This layer knows nothing about MQTT, TLS, or cloud protocols.

Layer 2 — /IOTCONNECT™ SDK: The communication abstraction layer. Handles discovery, authentication, MQTT connectivity, telemetry publishing, command callbacks, twin/shadow sync, OTA, and certificate management. Your firmware interacts with it through simple API calls.

Layer 3 — /IOTCONNECT™ Cloud: The platform services. Device management, telemetry storage, rules engine, dashboards, commands, OTA, and connectors.

The SDK is the bridge. It abstracts all cloud communication complexity so your firmware code remains clean, portable, and focused on device functionality.

SDK Public API (What Your Firmware Calls)

Based on the actual /IOTCONNECT™ SDK implementation, here is the complete public API surface your firmware interacts with:

Initialization and Connection:

Method	Purpose
`Init(cpId, uniqueId, environment, platform, options, callback, settingCallback)`	Initialize SDK with device credentials and platform identity
`Connect(successCallback, failedCallback, connectionStatusCallback)`	Establish connection to /IOTCONNECT™ cloud (handles Discovery + Auth + MQTT)
`Disconnect()`	Gracefully close cloud connection
`Dispose()`	Clean up all SDK resources

Telemetry (Device → Cloud):

Method	Purpose
`SendData(json)`	Publish telemetry data to /IOTCONNECT™ cloud
`SendImage(path)`	Upload image file to cloud storage
`UploadImage(filePath)`	Upload image with automatic handling
`UploadImageWithClassification(filePath, classification)`	Upload image with AI classification metadata

Device Identity Messages:

Method	Purpose
`GetHelloMessage(callback)`	Get device metadata, protocol info, and capability flags (mt: 200)
`GetAttributes(callback)`	Fetch template attribute definitions (mt: 201)
`GetSettings(callback)`	Fetch device twin/shadow desired properties (mt: 202)
`GetRules(callback)`	Fetch edge rules for local processing (mt: 203)
`GetChildDevices(callback)`	Get registered child devices list (mt: 204)
`GetPendingOTAUpdates(callback)`	Check for pending firmware updates (mt: 205)
`GetPendingCommands(callback)`	Check for pending commands (mt: 206)

Commands (Cloud → Device Callbacks):

Method	Purpose
`OnDeviceCommand(callback)`	Register handler for device commands from cloud
`OnOTACommand(callback)`	Register handler for OTA firmware update commands
`OnModuleCommand(callback)`	Register handler for module push commands
`OnSettingChangeCommand(callback)`	Register handler for twin/shadow setting changes
`OnAttrChangeCommand(callback)`	Register handler for attribute definition changes
`OnDeviceChangeCommand(callback)`	Register handler for child device changes

Acknowledgements:

Method	Purpose
`SendAckCmd(ackGuid, status, msg)`	Acknowledge command execution (success/failed)
`SendOTAAckCmd(ackGuid, status, msg)`	Acknowledge OTA update status
`SendAckModule(ackGuid, status, msg)`	Acknowledge module command execution
`UpdateSetting(property, value, version, callback)`	Report setting/twin property back to cloud

Certificate Management:

Method	Purpose
`OnCertificateReceived(callback)`	Handle certificate renewal from cloud
`OnCertSignedRequest(callback)`	Handle CSR-based certificate rotation
`SubmitCSR(csr, signature)`	Submit Certificate Signing Request for rotation

Responsibility Separation

Your Firmware / Application	/IOTCONNECT™ SDK (Handled For You)	/IOTCONNECT™ Cloud
Hardware drivers (GPIO, I2C, SPI, UART)	Discovery API call and endpoint resolution	Device registry and management
Sensor reading and data collection	MQTT connection over TLS (port 8883)	Telemetry ingestion and storage
Actuator and motor control	X.509 certificate authentication	Command routing and delivery
Business logic and local decisions	Automatic reconnection with backoff	Rules and event processing
Data filtering and aggregation	Telemetry JSON formatting and publishing	Dashboards and visualization
Calling SDK APIs when communication needed	Command reception and callback dispatch	OTA firmware management
Processing received commands	Twin/Shadow synchronization	Data connectors (S3, DynamoDB, etc.)
Device state management	Certificate rotation and renewal	REST API for integrations
Error handling for hardware	Offline storage and retry queue	User and role management

Data Flow Diagrams

SDK Internal Layers

Inside the SDK, the following internal layers handle cloud communication (your firmware never interacts with these directly):

Internal Layer	Responsibility	Key Components
Discovery	Resolves cloud endpoints from CPID + Environment	HTTPS call to discovery.iotconnect.io
Identity	Fetches device config, attributes, topics, auth type	Agent Sync API call
Broker	Manages MQTT connection lifecycle	MQTTnet client, TLS, QoS 1
Message Handler	Formats outgoing JSON, parses incoming commands	Protocol 2.1 message serialization
Certificate Manager	Handles cert rotation, CSR flow, renewal	X.509, private key management
Offline Storage	Queues telemetry when disconnected	File-based queue with configurable size
Data Validator	Validates telemetry against template schema	Attribute type checking before publish

Why This Architecture Matters

Portable: Same firmware code runs on any hardware. Only the SDK platform layer changes between MCU, Linux, Windows.

Maintainable: Cloud protocol changes (new message versions, endpoint migrations) are handled by updating the SDK NuGet package — zero firmware code changes.

Secure: Certificate management, TLS, and authentication are handled inside the SDK. Firmware developers cannot accidentally bypass security.

Testable: Firmware logic can be unit tested without cloud connectivity. Mock the SDK interface for isolated testing.

Resilient: Offline storage, automatic reconnection, and retry are built into the SDK. Firmware does not need to handle network failures.

Multi-platform: The SDK is available for C, Python, C#, Node.js, Java, Android, and iOS — all with the same architecture pattern.

SDK Configuration Options

When initializing the SDK, you configure these options (from SDKOptions):

Option	Description	Default
DiscoveryURL	Custom discovery endpoint (for non-default regions)	https://discovery.iotconnect.io
IsDebug	Enable verbose SDK logging	false
Certificate.CACertificatePath	Path to device CA certificate file (.pem)	Required for cert-auth
Certificate.PrivateKeyCertificatePath	Path to device private key file (.pem)	Required for cert-auth
Certificate.Password	Certificate password (if encrypted)	Optional
OfflineStorage.Disabled	Disable offline message queuing	false (enabled)
OfflineStorage.AvailSpaceInMb	Max disk space for offline queue	Unlimited
OfflineStorage.FileCount	Number of offline storage files	1
DevicePK	Device primary key (for symmetric auth)	Optional
IsDataFreqEnable	Enforce minimum telemetry send interval	true

ⓘ SDK AVAILABILITY

The /IOTCONNECT™ SDK is available for: C (embedded), Python, C# / .NET, Node.js, Java, Android, and iOS. All SDKs follow this same three-layer architecture pattern. The API surface is consistent across languages — learn once, apply everywhere.