Skip to content

sim-hw Overview

sim-hw (package name: eink-hw) is a Python device simulator that emulates the behavior of a physical Inklet e-ink device. It implements the full device-side IoT protocol, enabling end-to-end development and testing without physical hardware.

Repository: Inklet-2026/sim-hw

What It Does

sim-hw simulates the complete device lifecycle:

  1. Fleet Provisioning --- On first run, connects to AWS IoT Core with a claim certificate, obtains a device-specific certificate and Thing name, and stores them locally.

  2. MQTT Connectivity --- Connects to AWS IoT Core via X.509 mTLS, subscribes to command topics, and publishes heartbeats and state.

  3. Heartbeat Reporting --- Sends periodic heartbeat messages with hardware ID, timestamp, firmware version, and battery level.

  4. State Reporting --- Reports device state as arbitrary JSON via the up/state topic.

  5. Command Handling --- Receives and processes commands from the backend:

    • text --- Renders text to an 800x480 1-bit bitmap
    • claim_code --- Renders a large pairing code
    • bound --- Shows a binding confirmation message
    • unbound --- Clears the display and re-requests a claim code
    • already_bound --- Logs the event (no display action)

  6. Display Rendering --- Uses Pillow to render text and codes to 800x480 monochrome bitmaps, then pushes the rendered PNG to the sim-dashboard Fastify server via HTTP POST.

  7. NFC Payload Generation --- Generates an HMAC-signed NFC payload (inklet:1:{hwId}:{signature}) and writes it to the data directory. This can be used to test NFC-based device binding.

  8. Browser Integration --- Automatically opens the sim-dashboard in your default browser, pointed at the device's live display preview.

Architecture

sim-hw
├── MQTT Client (AWS IoT Device SDK)
│   ├── Publishes: heartbeat, state, request_claim
│   └── Subscribes: down/cmd
│
├── Fleet Provisioning Client
│   └── Claim cert → device cert + thingName
│
├── Display Renderer (Pillow)
│   └── Text → 800×480 1-bit PNG
│
├── NFC Generator
│   └── HMAC-SHA256 → nfc-payload file
│
└── sim-dashboard Client (HTTP)
    └── POST framebuffer to Fastify server

Simulated vs Real Device

Feature Real Device sim-hw
MQTT connection X.509 mTLS X.509 mTLS (same)
Fleet Provisioning On first boot On first run
Display Physical e-ink panel Rendered PNG pushed to sim-dashboard
Battery Hardware sensor Simulated (reported as constant)
NFC tag Physical NFC chip File-based payload generation
Firmware Embedded C/Rust Python simulator

Multiple Devices

You can run multiple sim-hw instances simultaneously by using different --data-dir paths. Each data directory represents a separate physical device with its own hardware ID, certificates, and state.

Next Steps

  • Getting Started --- Install and run your first simulated device
  • NFC Binding --- How NFC payload generation and binding works
  • Commands --- Detailed command handling and display rendering