Spenser - a developer's companion, published by Zeora. This guide is not an authorized publication; it is the continuous build for version 1.0.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/costateixeira/spenser/tree/master and changes regularly. See the Directory of published versions

Firmware

The firmware runs on an ESP32-S3-based dispenser using the M5Stack AtomS3 Lite and M5Stack Atomic Motion Base, designed to dispense chocolate upon receiving FHIR MedicationRequests over HTTP.

It supports:

• A local Wi-Fi configuration portal (via captive portal or button)
• RESTful endpoints for FHIR interaction
  • 📦 FHIR InventoryReport for reporting (GET) and adjusting (POST) inventory
  • 🏥 Accept MedicationRequest resources via HTTP POST and reply with MedicationDispense
• RESTful services for debugging and inventory management

Usage

1. Install PlatformIO - Note: VSCode works, VSCodium doesn't
2. Connect to a USB port. On Windows, use Microsoft drivers - DO NOT use other drivers like CH340 etc.
3. From the firmware folder, run PlatformIo to compile, upload and monitor
4. Please help improve the code - PRs are more than welcome.

🌐 FHIR endpoints

These endpoints conform to FHIR R5:

GET /metadata

• Returns a FHIR CapabilityStatement
• Declares support for the FHIR resources

POST /MedicationRequest

• Accepts a FHIR MedicationRequest resource (JSON)
• Dispenses either dark or milk chocolate depending on the medication code
• Responds with a MedicationDispense resource
• If out of stock, responds with a declined MedicationDispense

POST /InventoryReport

• Accepts a FHIR InventoryReport resource
• Supports:
  • countType: snapshot — replace inventory
  • countType: difference — adjust inventory incrementally
• Validates inventory constraints (e.g. no negative values)
• Responds with the updated inventory or an error

GET /InventoryReport

• Returns a snapshot-style InventoryReport representing current stock
• Includes bin locations and item status

⚙️ Configuration & Debug Endpoints

These are utility endpoints for diagnostics, setup, and interactive testing.

Wi-Fi Configuration

UI & Information

Debugging & Manual Control

Captive Portal Compatibility

These endpoints redirect to /success to handle platform-specific captive portals:

• /generate_204
• /hotspot-detect.html
• /fwlink
• /connecttest.txt
• /ncsi.txt
• /i

🚀 Wifi and boot

When started, the firmware tries to connect to the Wi-Fi network defined in WiFiCredentials.h. It also creates an AP with an SSID spenser, and an IP 192.168.4.1.
So, to get started, simply connect to the spenser Wi-Fi network and go to http://192.168.4.1.

🔋 Hardware Behavior

• Button Pin: GPIO 41
  • Hold 3 seconds during boot: enter Wi-Fi config mode
  • Short press during runtime: dispense one dark chocolate - aka PANIC ! / Hit Me !!
• RGB LED Pin: GPIO 35 (WS2812)
• Servos:
  • Servo 0: dark chocolate
  • Servo 1: milk chocolate
  • Default dispenseAngle: 97°

📦 Storage

• SPIFFS is used to serve index.html and UI assets.
• Preferences are used to persist the forceConfig flag for Wi-Fi setup.

🔋 Battery Monitoring

(WIP / YMMV)

• Reads voltage from the INA226 sensor on the Atomic Motion Base.
• Estimates battery % using a polynomial fit.
• Query battery state via GET /battery

🧪 Manual Testing

Use these endpoints to test functionality:

• GET /flashServo1 — Dispense dark chocolate manually
• GET /flashServo2 — Dispense milk chocolate manually
• GET /setColor?red=0&green=255&blue=0 — Set LED to green
• GET /resetInventory?dark=20&milk=20 — Reset inventory

✅ Example MedicationRequest POST

{
  "resourceType": "MedicationRequest",
  "id": "req-123",
  "status": "active",
  "intent": "instance-order",
  "medicationCodeableConcept": {
    "coding": [
      {
        "code": "chocolate-dark",
        "display": "Dark Chocolate"
      }
    ]
  },
  "dosageInstruction": [
    { "text": "Dispense one dark chocolate" }
  ],
  "subject": { "reference": "Patient/example" }
}