Build from your agent.

Private workspaces. Device events. App layouts published through API or MCP.

# HardwareBlocks / developer beta 0.3

Tiny physical inputs for software built with AI. Choose a fixed kit, open the web app, claim your box and build its interface with Claude, Codex or your own code.

Four assembled kits: Camera, Motion, Distance, Climate + Touch. Each costs 799 DKK including VAT and EU delivery, with an installed rechargeable battery. Expected delivery: two weeks. Order at https://hardwareblocks.com/order/. Nothing is charged until the kit is ready for dispatch. Physical assembly and bench testing are fulfilment steps, not claimed completed by this software release.

## What works now

Public kits, parts, schemas, recipes and status endpoints. Private workspaces, device provisioning/claiming, HTTPS telemetry and camera snapshots. A web app with metric, status, JSON and camera widgets; publish layouts through REST or MCP. Simulations for building before the box arrives. Ordering and private order administration with Stripe reconciliation.

Not released: native iOS/Android apps, Bluetooth commissioning, phone gateway, arbitrary cloud code hosting, OTA firmware or push notifications. Use Wi-Fi for the current hardware integration. Create your own backend for AI inference and notifications. Do not claim an App Store app is available. Physical firmware and assembly require a bench test on the actual sensor revisions before dispatch.

## 1. Open the app

https://hardwareblocks.com/app/
Create a workspace and save the downloaded recovery key. No email login or lost-key recovery in this beta. Add a simulated kit and click Build starter layout. Simulation labels remain visible. To use a shipped box, enter its claim code; the device must separately be configured for Wi-Fi and send its first event.

## 2. Public REST

GET /api/status — actual feature availability
GET /api/kits — kits, BOM, suppliers, assembly notes and limitations
GET /api/schema — validated sensor events and app format
GET /api/shop — prices, delivery and countries
GET /api/catalog — illustrative use-case recipes
GET /api/recipes/{fridge|parking|bike|ski}
GET /api/examples/{fridge|parking|bike|ski} — legacy simulated use-case examples

Legacy recipes describe application-level ideas. New hardware integrations MUST use /api/schema event names instead. Force means a relative force pad, not air pressure. Motion means movement of the box; PIR presence is a separate sensor.

## 3. Workspace REST

POST /api/v1/workspaces — no body; returns id and private workspace_token once.
All following requests: Authorization: Bearer <workspace_token>.
GET /api/v1/devices
POST /api/v1/devices with {"kit_id":"climate-touch","name":"Room simulation"} — creates a simulation only.
POST /api/v1/claim with {"claim_code":"<code supplied with box>"} — claims a provisioned physical device once.
GET /api/v1/devices/{id}/events — latest 100 events.
POST /api/v1/devices/{id}/simulate with {"type":"climate.sample","data":{"temperature_c":22.4,"humidity_pct":48}} — simulation devices only.
GET /api/v1/app — current app and version.
PUT /api/v1/app with {"expected_version":0,"app":{"title":"My room","widgets":[]}} — publish layout; fetch its version first. Conflicts return 409.

Widget types: metric, status, json, camera. Each has label, device_id and event_type. Metric/status also have field and optional unit. Only owned devices and kit-compatible events are accepted. Labels are plain text. No scripts or HTML execute. Refresh the app to see published changes.

Example widget: {"type":"metric","label":"Temperature","device_id":"<actual device id>","event_type":"climate.sample","field":"temperature_c","unit":"°C"}.
Limits: 20 devices/workspace, 1,000 recent events/device, 24 widgets/app. Requests are bounded and rate-limited. Save keys privately; never commit them or include them in public prompts.

## 4. Physical ingestion

Factory provision: POST /api/admin/devices, administrator bearer token, {"kit_id":"motion","name":"Motion Kit"}. Returns device_token and claim_code. Flash the device token; give the owner only the claim code. A workspace key must never be put on a device.

After claiming, firmware POSTs https://hardwareblocks.com/api/v1/ingest with Authorization: Bearer <device_token>, Content-Type: application/json and {"type":"motion.sample","data":{"moving":true,"acceleration_g":{"x":0.1,"y":0.2,"z":1.1},"rotation_dps":{"x":2,"y":3,"z":15}}}.
Optional observed_at must be within 24 hours. Verify TLS certificates in firmware. The server assigns physical/simulation source; the client cannot override it.

Camera: POST binary image/jpeg to /api/v1/snapshot with its device token. Maximum 256 KiB; dimensions up to 4096. Only the latest private image is retained. Owners GET /api/v1/devices/{id}/image with workspace authentication. No public image link is generated. The camera.snapshot event records dimensions/time, and image_url is null. Display with a camera widget.

## 5. MCP

https://hardwareblocks.com/mcp — stateless Streamable HTTP with JSON responses, POST only.
Accept: application/json, text/event-stream. Content-Type: application/json.
Protocol revisions: 2025-11-25, 2025-06-18, 2025-03-26.
Public tools: get_status, list_blocks, list_recipes, get_recipe, list_kits, get_sensor_schema.
Private: list_devices, get_events({device_id}), get_app, publish_app({app,expected_version}). Set Authorization: Bearer <workspace key> privately in a client supporting HTTP headers. OAuth discovery is not implemented; clients requiring OAuth cannot use private tools yet.

Initialize: {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"my-agent","version":"1"}}}.
Send notifications/initialized, then tools/list and tools/call with negotiated MCP-Protocol-Version.
Example: {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_kits","arguments":{}}}.
Resource: hardwareblocks://docs/getting-started. Prompt: get_started with recipe fridge, parking, bike or ski. Recipe pseudocode is illustrative, not an SDK package.

## Apple architecture

The current web app does not need App Store review. For a future native app, keep pairing, device access and the renderer in the reviewed app. AI-authored logic runs on a backend; the app receives validated data/layout documents. This is a design recommendation, not a guarantee of review approval.
Apple 2.5.2 restricts downloaded executable code that changes features. 4.7 permits some HTML5/JavaScript mini-app experiences with extra requirements, including limits on exposing native APIs. Physical goods use external payment methods under 3.1.3(e).
https://developer.apple.com/app-store/review/guidelines/

## Hardware and shipping

XIAO ESP32S3/Sense, 3.3 V sensors, protected 3.7 V LiPo and one charging path through XIAO. Do not parallel the Grove base charger. The XIAO 5 V pin is off on battery; use a verified 3.3 V sensor harness. Test runtime, enclosure fit, sensor revisions, charging and complete firmware before dispatch. Continuous camera use should use USB-C; no battery-life promise is made.
Installed lithium cells can be shipped internationally with appropriate test documentation, packaging and carrier acceptance. Current shipping is EU only. The 500 mAh reference cell is 1.85 Wh; obtain the actual cell UN 38.3 test summary and verify route-specific carrier rules.
https://wiki.seeedstudio.com/xiao_esp32s3_getting_started/
https://www.adafruit.com/product/1578
https://www.iata.org/contentassets/05e6d8742b0047259bf3a700bc9d42b9/lithium-battery-guidance-document.pdf

Images are concept renders. Do not infer waterproofing, GPS, cellular coverage or safety certification from them.


# Fixed kits

## Camera Kit
A compact camera and door sensor for snapshots, visual check-ins and fridge experiments.
Parts: XIAO ESP32S3 Sense, Grove Base for XIAO, Grove Magnetic Switch, Protected LiPo 3.7 V / 500 mAh (Adafruit 1578)
Camera on Sense connector; reed on D0/GPIO1; power the sensor from 3.3 V. Add a small magnet. No SD card is needed for the initial network prototype. Connect the protected cell through a polarity-checked harness and transport switch to XIAO BAT pads. Use only the XIAO charger; do not wire the Grove base battery connector. Power all sensors from the 3.3 V rail, as the 5 V pin is off on battery.
Limits: Fridge use needs condensation, lighting, power-cable and Wi-Fi tests. The launch kit is a developer kit, not a food freshness detector.
Power: Installed rechargeable 3.7 V LiPo battery; charge via USB-C. Cable included, mains adapter not included. Runtime is not yet specified.

## Motion Kit
Acceleration and rotation for bike movement alerts, gesture controls and SkiTik experiments.
Parts: XIAO ESP32S3, Grove Base for XIAO, Grove 6-Axis Accelerometer & Gyroscope (LSM6DS3), Protected LiPo 3.7 V / 500 mAh (Adafruit 1578)
LSM6DS3 on 3.3 V I2C: SDA D4/GPIO5 and SCL D5/GPIO6. Calibrate orientation after mounting. Connect the protected cell through a polarity-checked harness and transport switch to XIAO BAT pads. Use only the XIAO charger; do not wire the Grove base battery connector. Power all sensors from the 3.3 V rail, as the 5 V pin is off on battery.
Limits: Remote alerts need Wi-Fi or a separately implemented phone/gateway relay. No GPS, theft recovery guarantee or weatherproof rating.
Power: Installed rechargeable 3.7 V LiPo battery; charge via USB-C. Cable included, mains adapter not included. Runtime is not yet specified.

## Distance Kit
A short-range distance sensor for a garage space, a desk or an object-presence experiment.
Parts: XIAO ESP32S3, Grove Base for XIAO, Grove Time of Flight (VL53L0X), Protected LiPo 3.7 V / 500 mAh (Adafruit 1578)
VL53L0X on 3.3 V I2C: SDA D4/GPIO5, SCL D5/GPIO6, address 0x29. Use one range sensor per kit. Connect the protected cell through a polarity-checked harness and transport switch to XIAO BAT pads. Use only the XIAO charger; do not wire the Grove base battery connector. Power all sensors from the 3.3 V rail, as the 5 V pin is off on battery.
Limits: Design around the manufacturer's recommended 30–1000 mm range. Indoor prototype; not a safety system for parking or driving.
Power: Installed rechargeable 3.7 V LiPo battery; charge via USB-C. Cable included, mains adapter not included. Runtime is not yet specified.

## Climate + Touch Kit
Temperature, humidity and a force-sensitive pad for room monitors, touch triggers and presence experiments.
Parts: XIAO ESP32S3, Grove Base for XIAO, Grove Temperature & Humidity (SHT31), Grove Round Force Sensor (FSR402), Protected LiPo 3.7 V / 500 mAh (Adafruit 1578)
SHT31 uses I2C D4/D5. FSR402 uses analog A0/GPIO1 with a dedicated 3.3 V harness. The two interfaces do not conflict. Connect the protected cell through a polarity-checked harness and transport switch to XIAO BAT pads. Use only the XIAO charger; do not wire the Grove base battery connector. Power all sensors from the 3.3 V rail, as the 5 V pin is off on battery.
Limits: The force pad detects relative pressure; it is not a calibrated weighing or air-pressure instrument. Keep the temperature sensor away from controller heat.
Power: Installed rechargeable 3.7 V LiPo battery; charge via USB-C. Cable included, mains adapter not included. Runtime is not yet specified.

# Complete build recipes

## Fridge cam (fridge)
A snapshot when the door closes. Your shopping app gets the update.
Build a fridge dashboard with the latest snapshot, capture time and an editable shopping list. Start with the provided simulated event. Use a local placeholder image; image_url is null because no hardware is connected. Define a replaceable device adapter. Clearly show stale images and disconnected devices.
Example only: {"source":"simulation","type":"fridge.snapshot","device_id":"demo-fridge","door":"closed","image_url":null,"captured_at":"2026-10-29T12:00:00Z"}
A closed fridge needs controlled lighting. Test condensation protection, mounting and Wi-Fi reception. A photo does not determine food freshness.

## Parking sensor (parking)
Distance becomes occupancy. Your app decides what happens next.
Build a single-space parking dashboard using simulated distance events. Show available, occupied or unknown. Use a configurable calibrated threshold, require five seconds of stable readings before switching status, and show unknown when data is stale. Put device access behind a replaceable adapter.
Example only: {"source":"simulation","type":"parking.occupancy","device_id":"demo-parking","occupied":true,"distance_cm":84,"observed_at":"2026-10-29T12:00:00Z"}
Choose and calibrate the sensor for the installation. Account for weather and passing objects. This detects occupancy; it is not a collision-avoidance system.

## Bike guard (bike)
A motion event from your bike. An alert defined by you.
Build a bike movement alarm with arm/disarm controls, adjustable sensitivity and visible connection status. Start with the provided simulated motion event and show alerts locally. Remote notifications require a connected phone or gateway with internet access. Separate a mock adapter from future hardware access; do not imply GPS tracking.
Example only: {"source":"simulation","type":"bike.motion","device_id":"demo-bike","armed":true,"motion_detected":true,"connection":"gateway-online","observed_at":"2026-10-29T12:00:00Z"}
Launch Motion Kit sends through Wi-Fi (including a suitable phone hotspot). A native Bluetooth phone relay is not released. Remote alerts require internet connectivity. Test background behaviour and battery life. Movement alerts are not GPS tracking or a replacement for a lock.

## SkiTik (ski)
Acceleration and rotation become a session you can explore.
Build a ski-session explorer with a motion timeline and candidate turns from simulated accelerometer and gyroscope data. Separate raw measurements from estimates. Include calibration and connection status. Use a replaceable device adapter and do not claim measured accuracy or snow-tested performance.
Example only: {"source":"simulation","type":"ski.motion","device_id":"demo-skitik","acceleration_m_s2":{"x":1.2,"y":0.6,"z":9.5},"gyroscope_deg_s":{"x":2.4,"y":18.2,"z":-3.1},"observed_at":"2026-10-29T12:00:00Z"}
Launch Motion Kit sends through Wi-Fi (including a suitable phone hotspot). A native Bluetooth phone relay is not released. SkiTik is an existing development project. Its CAD reference is a 50 × 32 mm low-profile USB-C pod. That is reference geometry, not a guaranteed HardwareBlocks specification. On-snow accuracy and cold-weather performance need validation.