The SDK Layered Architecture

Who this is for: Developers who want to understand how the SDK is structured internally, and anyone porting it to new hardware.

What you'll learn: The five layers of the SDK, what each one does, and why the design keeps the SDK portable from PCs down to embedded microcontrollers.

The SDK follows a layered architecture that separates responsibilities, protects the public API, and ensures full portability across platforms. Each layer has a clear role, so the SDK can evolve internally without affecting the applications that use it.

Screenshot (image2.png): The SandGrain SDK layered architecture, Application to Middleware to Services to Utils to Portability.

The layers, top to bottom, are Application, Middleware, Services, Utils, and Portability, with Client Platform Libraries beneath them (outside the SDK boundary).

Application Layer

The entry point and public API. It drives the Middleware state machine in a loop until an operation reaches a final state, then returns the corresponding sgr_sdk_status_t code. API calls are blocking as shipped, but the loop can be wrapped or replaced (a task scheduler or event loop) without touching lower layers. The functions differ by mode:

DEVICE_MODE: SGR_SDK_Initialize, SGR_SDK_Authenticate_Via_GW, SGR_SDK_Verification_FW, SGR_SDK_Installation.
GATEWAY_MODE: SGR_SDK_Initialize, SGR_SDK_Authentication_Token_To_Server, SGR_SDK_Authentication_Server_To_Token, SGR_SDK_GW_Run.

Middleware Layer

The authentication protocol logic, fully platform-independent (no hardware-specific code), implemented as an explicit state machine. It returns SGR_MW_OK / SGR_MW_AUTH_FAILED / SGR_MW_COMM_ERROR / SGR_MW_ERROR, or an in-progress status. It exposes sgr_mw_init and sgr_mw_authenticate_via_gw (Device mode), and sgr_mw_authentication_token_to_server / sgr_mw_authentication_server_to_token / sgr_mw_gw_authenticate_device (Gateway mode).

Services Layer

Reusable building blocks: the Frame Codec Service (framing, encode, decode), the Token Service (crypto-chip interaction), and the Server Service (next-node communication), plus Utils (CRC, hex conversion). Gateway mode adds the Device Service (Gateway to devices) and the Database Service (auth DB, device registration, CRC-to-TID resolution).

Portability Layer

Abstracts the platform-dependent capabilities: device and server communication, and timing/delay. Porting the SDK to a new platform happens entirely in this layer, nothing above it needs to change.

Client Platform Libraries

The target environment's primitives (OS, transport stacks, drivers). These are not part of the SDK itself; they sit beneath the boundary.

Why this matters for portability

Because everything hardware-specific lives in the Portability Layer, the same SDK runs on very different setups. The shipped proof of concept targets a virtualized environment (a USB SandGrain Token plus PC MQTT); MCU ports are implemented per project in the Portability Layer. This is exactly what lets the Bluetooth LE and cellular variants run the same core protocol on Nordic boards.