Skip to content

IoT Managed Integrations Device SDK — Middlewares

Minimum ACE package for IoT Managed Integrations supporting WiFi, Z-Wave, and Zigbee protocols.

Architecture Overview

The middleware follows a layered architecture with process isolation:

Cloud (AWS IoT Core)
  ↓ MQTT
IoTMI Hub SDK
  ↓
Middleware Service (zigbee_svc / zwave_svc / wifi_svc)
  ↓ AIPC (ACE IPC)
DPK HAL Daemon (zigbeed / zwaved / wifid)
  ↓ D-Bus
Protocol Gateway (Z3 Gateway / ZIP Gateway / wpa_supplicant)
  ↓ Serial/SPI/USB
Radio Hardware

Key architectural patterns:

Pattern Purpose
AIPC (ACE IPC) Client-server RPC between middleware services and HAL daemons
EventMgr Publish-subscribe event system for async notifications (node added/removed, network status)
HSM Hierarchical State Machine managing connection/AP lifecycle states for WiFi, HostAP, and Z-Wave
D-Bus IPC HAL daemons communicate with protocol gateways via D-Bus (fxnDbusClient)

Directory Structure

IotManagedIntegrationsDeviceSDK-Middlewares/
├── build.sh                    # Main build script
├── iotmi-ace-general/          # Core ACE framework
│   ├── framework/              #   AIPC, CLI, EventMgr, Dispatcher, OSAL
│   ├── middleware/             #   WiFi, Zigbee, Network Manager, HostAP
│   ├── dpk/                    #   HAL stubs, OSAL (POSIX)
│   └── external/               #   Third-party (ceedling, uthash)
├── iotmi-ace-dpk/              # Device Platform Kit (HAL implementations)
│   └── iotmi/dpk/ace_hal/      #   WiFi, Zigbee, Z-Wave HAL + daemons
├── iotmi-ace-project/          # Build configuration
│   └── iotmi/ace/ace_config/   #   iotmi.conf, iotmi.build
├── iotmi-ace-zwave-mw/         # Z-Wave middleware service
├── iotmi-ace-zware/            # Z-Wave HCAPI library (Silicon Labs)
├── iotmi-ace-z3-gateway/       # Zigbee Z3 Gateway (Silicon Labs Gecko SDK)
├── greengrass/components/      # Greengrass deployment recipes
│   ├── AceCommon/              #   Core libs + shared binaries
│   ├── AceWifi/                #   WiFi service + network manager
│   ├── AceZwave/               #   Z-Wave service + libs
│   ├── AceZigbee/              #   Zigbee service + libs
│   └── AceCli/                 #   CLI diagnostic tool
└── scripts/                    # Build/release helper scripts

Components

Core Framework (iotmi-ace-general)

Foundational services all middleware depends on:

  • AIPC: Inter-process communication framework for cross-process RPC
  • EventMgr: Publish-subscribe event notification system
  • Dispatcher: Message routing and handler registration
  • CLI: Command-line diagnostic interface
  • OSAL: OS abstraction layer (threads, semaphores, mutexes)

WiFi Middleware

  • WiFi STA Manager: Scanning, AP selection, connection lifecycle, antenna diversity, DHCP
  • HostAP Service: SoftAP management for device provisioning via hostapd
  • Network Manager: Unified network status, IP configuration, bridged networking, DHCP server, HTTP connectivity tests

Zigbee Middleware

  • Zigbee Service: Device discovery, permit join, ZCL cluster commands (on/off, level, color, HVAC, door lock, IAS, OTA)
  • Z3 Gateway: Silicon Labs Gecko SDK-based Zigbee coordinator (NCP host application)
  • Zigbee HAL: zigbeed daemon bridging middleware to Z3 Gateway via D-Bus

Z-Wave Middleware

  • Z-Wave Service: Node inclusion/exclusion, command class handling, network health, firmware updates
  • Z-Wave HCAPI (zware): Silicon Labs Z/IP API library for Z-Wave controller communication
  • Z-Wave HAL: zwaved daemon bridging middleware to ZIP Gateway via D-Bus

Device Platform Kit (iotmi-ace-dpk)

Hardware abstraction layer with per-protocol daemons:

Daemon Role
wifid WiFi HAL daemon (wpa_supplicant integration)
zigbeed Zigbee HAL daemon (Z3 Gateway communication)
zwaved Z-Wave HAL daemon (zware/ZIP Gateway communication)
KVS HAL Key-value storage abstraction
Log HAL Logging abstraction

Build System

Hybrid build: GNU Make (ACE framework) + CMake (DPK) + shell scripts (external deps).

The build.sh script orchestrates:

  1. Copies iotmi-ace-general to a temp build dir, merges iotmi-ace-zwave-mw
  2. Runs make package with product config (iotmi.conf)
  3. Builds external dependencies (hostapd, zware, z3-gateway)
  4. Builds DPK via CMake
  5. Packages into Greengrass components (image_gg/)

Each component declares itself in module.conf (YAML) specifying sources, headers, library type, dependencies, and feature flags.

Build Instructions

Prerequisites

  • GCC or cross-compilation toolchain
  • CMake
  • Python 3 (with pyyaml)
  • GNU Make

Build for host platform

./build.sh linux

Cross-compile

Source the toolchain environment file which provides environment variables (CC, CFLAGS, etc.):

source <toolchain-env-file>
./build.sh cross

Output is in image_gg/.

Build with HAL stubs

./build.sh linux stub

Clean build

./build.sh clean

Deployment

Prerequisites

Follow the IoT Managed Integrations Hub SDK deployment guide to set up your hub device.

Copy middleware to hub

The generated middleware is in the image_gg/ folder. Copy its contents to the middleware folder on your hub device. It should contain: AceCli, AceCommon, AceWifi, AceZigbee, AceZwave.

Optional: Reference Guide

./build.sh make_docs

This generates a porting_guide/ folder. Open index.html to view:

cd porting_guide
firefox index.html

Configuration

./build.sh make_config

Opens an interactive menu to set/unset product configurations.