# 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. Each box has one primary sensor module and costs 99 EUR including VAT. Shipping and handling costs 30 EUR per order to the EU, 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 selected 400 mAh cell (Electrokit 41016062, also ordered for SkiTik prototypes) is 1.48 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.


One module per box: camera only (no door sensor), one IMU (accelerometer + gyroscope), one distance module, or one climate module (temperature + humidity). The stable API kit id climate-touch now names the Climate Kit; no force sensor is included. Button and force modules are future extensions. The camera board has an unused microphone, not exposed by the kit.


## Shop and power
Browse https://hardwareblocks.com/shop/, open a product page, add different devices to the cart, and check out once. Orders accept an items array of {kit_id, quantity}; server prices are authoritative. Maximum 10 devices, 99 EUR each plus 30 EUR shipping once per order. The receipt snapshots every model and quantity. A power bank or regulated 5 V USB supply extends operation through USB-C. Check low-current compatibility for sleeping sensors. Power bank and mains adapter are not included.

## Enclosure and indicator
Custom black PA12 nylon enclosures made by MJF/SLS 3D printing are the proposed first-batch manufacturing route. No CAD-fit or finished enclosure has been validated yet. The image is a concept. XIAO ESP32S3 has an orange user LED and a red charging LED; the proposed enclosure uses a light pipe for the orange user LED.


# Fixed kits

## Camera Kit
One compact camera for snapshots, visual check-ins and fridge experiments.
In the box:
- 1 × XIAO ESP32S3 Sense, SKU 113991115, with camera daughterboard
- 1 × supplied Wi-Fi antenna
- 1 × protected 400 mAh LiPo battery (Electrokit 41016062), installed
- 1 × protective enclosure with sensor-specific openings
- 1 × USB-C data/power cable
- 1 × installed wiring and battery connector set, transport switch and insulated mounts
- Device claim code and setup guide
Camera module on the XIAO Sense connector. No extra door sensor. Onboard microphone is not exposed or used by this kit. Connect the protected 400 mAh cell through a polarity-checked harness and transport switch to XIAO BAT pads. Use only the XIAO charger. Power the sensor from 3.3 V; the 5 V pin is off on battery. Verify charge current against the cell rating and inhibit charging below 0 °C.
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 protected 3.7 V / 400 mAh LiPo, charged through USB-C. Use a USB power bank or regulated 5 V USB supply for longer runs. Power bank and mains adapter not included. Runtime must be measured for your firmware.

## Motion Kit
Acceleration and rotation for bike movement alerts, gesture controls and SkiTik experiments.
In the box:
- 1 × XIAO ESP32S3, SKU 113991114
- 1 × supplied Wi-Fi antenna
- 1 × Grove LSM6DS3 accelerometer + gyroscope, SKU 105020012
- 1 × protected 400 mAh LiPo battery (Electrokit 41016062), installed
- 1 × protective enclosure with sensor-specific openings
- 1 × USB-C data/power cable
- 1 × installed wiring and battery connector set, transport switch and insulated mounts
- Device claim code and setup guide
One LSM6DS3 IMU module (acceleration and rotation). Direct 3.3 V I2C harness: SDA D4/GPIO5, SCL D5/GPIO6. Calibrate orientation after mounting. Connect the protected 400 mAh cell through a polarity-checked harness and transport switch to XIAO BAT pads. Use only the XIAO charger. Power the sensor from 3.3 V; the 5 V pin is off on battery. Verify charge current against the cell rating and inhibit charging below 0 °C.
Limits: Remote alerts need Wi-Fi or a separately implemented phone/gateway relay. No GPS, theft recovery guarantee or weatherproof rating.
Power: Installed protected 3.7 V / 400 mAh LiPo, charged through USB-C. Use a USB power bank or regulated 5 V USB supply for longer runs. Power bank and mains adapter not included. Runtime must be measured for your firmware.

## Distance Kit
A short-range distance sensor for a garage space, a desk or an object-presence experiment.
In the box:
- 1 × XIAO ESP32S3, SKU 113991114
- 1 × supplied Wi-Fi antenna
- 1 × Grove VL53L0X distance sensor, SKU 101020532
- 1 × protected 400 mAh LiPo battery (Electrokit 41016062), installed
- 1 × protective enclosure with sensor-specific openings
- 1 × USB-C data/power cable
- 1 × installed wiring and battery connector set, transport switch and insulated mounts
- Device claim code and setup guide
One VL53L0X distance module. Direct 3.3 V I2C harness: SDA D4/GPIO5, SCL D5/GPIO6, address 0x29. Connect the protected 400 mAh cell through a polarity-checked harness and transport switch to XIAO BAT pads. Use only the XIAO charger. Power the sensor from 3.3 V; the 5 V pin is off on battery. Verify charge current against the cell rating and inhibit charging below 0 °C.
Limits: Design around the manufacturer's recommended 30–1000 mm range. Indoor prototype; not a safety system for parking or driving.
Power: Installed protected 3.7 V / 400 mAh LiPo, charged through USB-C. Use a USB power bank or regulated 5 V USB supply for longer runs. Power bank and mains adapter not included. Runtime must be measured for your firmware.

## Climate Kit
One temperature and humidity module for room monitoring and climate experiments.
In the box:
- 1 × XIAO ESP32S3, SKU 113991114
- 1 × supplied Wi-Fi antenna
- 1 × Grove SHT31 temperature + humidity sensor, SKU 101020212
- 1 × protected 400 mAh LiPo battery (Electrokit 41016062), installed
- 1 × protective enclosure with sensor-specific openings
- 1 × USB-C data/power cable
- 1 × installed wiring and battery connector set, transport switch and insulated mounts
- Device claim code and setup guide
One SHT31 module measuring temperature and humidity. Direct 3.3 V I2C harness on D4/D5. Vent the enclosure and separate the sensor from controller heat. Connect the protected 400 mAh cell through a polarity-checked harness and transport switch to XIAO BAT pads. Use only the XIAO charger. Power the sensor from 3.3 V; the 5 V pin is off on battery. Verify charge current against the cell rating and inhibit charging below 0 °C.
Limits: Keep the sensor ventilated and away from controller heat. Not a certified food-safety instrument. No touch or force sensor included.
Power: Installed protected 3.7 V / 400 mAh LiPo, charged through USB-C. Use a USB power bank or regulated 5 V USB supply for longer runs. Power bank and mains adapter not included. Runtime must be measured for your firmware.

# Complete build recipes

## Fridge cam (fridge)
A snapshot on a schedule or on request. 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","image_url":null,"captured_at":"2026-10-29T12:00:00Z"}
The kit includes only the camera sensor. Trigger snapshots on a schedule or through your own firmware. Automatic door events require a separate sensor, not included. A closed fridge needs controlled lighting. Test condensation, mounting and Wi-Fi. Photos do 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.

## Build guides and product answers

- [What is HardwareBlocks?](https://hardwareblocks.com/guides/what-is-hardwareblocks/) — HardwareBlocks combines four assembled sensor kits with a private web app, a documented REST API and an MCP server. Use it to prototype an idea that needs camera images, movement, distance, or temperature and humidity. Start with simulated data, then connect a provisioned box over Wi-Fi.
- [How to build an AI hardware demo](https://hardwareblocks.com/guides/build-an-ai-hardware-demo/) — Start with a simulated sensor in the HardwareBlocks web app. Publish a starter dashboard, then give your coding assistant the sensor schema and ask it to adapt the interface. Replace simulation with a claimed, connected device when the hardware is ready. No physical kit is needed for the first software demo.
- [Build a room temperature and humidity monitor](https://hardwareblocks.com/guides/room-climate-monitor/) — Use the HardwareBlocks Climate Kit to measure temperature and relative humidity with one SHT31 module. Prototype the dashboard using climate.sample events, then read the same fields from a claimed Wi-Fi device. Any alerts or historical storage are application features you implement.
- [Build a bike movement alert prototype](https://hardwareblocks.com/guides/bike-motion-alert/) — The HardwareBlocks Motion Kit can provide acceleration, rotation and a moving flag for a bike movement experiment. Your application decides when the bike is armed and when to notify you. The current kit needs Wi-Fi coverage; it is not a GPS tracker or a standalone theft alarm.
- [Build a distance and object-presence demo](https://hardwareblocks.com/guides/distance-occupancy-sensor/) — Use a distance measurement and a calibrated threshold to prototype object presence. The HardwareBlocks Distance Kit uses a VL53L0X time-of-flight sensor and distance.sample events. Its API accepts 0–2,000 mm, but usable physical range depends on the target, light, mounting and sensor setup.
- [Build an AI camera and fridge demo](https://hardwareblocks.com/guides/ai-camera-fridge-demo/) — Start with the HardwareBlocks Camera Kit for a private snapshot dashboard. To turn an image into a draft shopping list, your own backend retrieves the image, calls a vision model and asks the user to review the result. HardwareBlocks supplies the camera-data interface; AI inference is a separate integration.
- [Development board comparison](https://hardwareblocks.com/compare/)
- [FAQ](https://hardwareblocks.com/faq/)