Apparatus Hardware Configuration Guide
Audience: Apparatus builders, LLMs assisting with component selection, and anyone configuring the physical aspects of a Juvantia Apparatus.
1. What is an Apparatus?
In the Juvantia ecosystem, an Apparatus is a static infrastructure element (barrier, vending machine, charging station, informative terminal) that interacts with Robulus units nearby.
Key Characteristics:
- BLE Only: Apparatuses do not typically use Wi-Fi. They communicate via Bluetooth Low Energy to minimize power consumption and interference.
- Standalone: They verify user rights (passes) offline using cryptographic signatures.
- Micro-Services: Each apparatus performs a specific localized task in the park.
2. Supported Microcontrollers
While any ESP32 will work, we recommend:
| Chip | Pros | Recommended For |
|---|---|---|
| ESP32-C3 | Cheap, Low Power, RISC-V | Small barriers, lights, info-points. |
| ESP32-S3 | Powerful, many GPIOs | Complex machines with many sensors/actuators. |
| ESP32 (Original) | Tried and true | Legacy hardware or simple relays. |
3. Powering Your Apparatus
Power Sources
- Mains (Universal Energy 12V): Easiest for permanent installations.
- Battery (LiPo/Li-ion): Requires power management. Use
Deep Sleepif the apparatus doesn't need to be always discoverable (Phase 3). - Solar: Ideal for outdoor barriers.
4. Typical Component Wiring
4.1 Digital Relay (for Lamps/Pumps)
ESP32 Pin ───── Signal (IN)
GND ───── GNDMost relay modules are "Active Low". Ensure your user_setup() sets the pin to HIGH initially to prevent accidental triggering on boot.
4.2 Servo Motor (for Barriers/Gates)
ESP32 Pin (PWM) ─── Signal (Yellow/White)
External 5V ─── VCC (Red)
Common GND ─── GND (Black/Brown)Note: ESP32-C3/S3 pins are 3.3V, which usually works for 5V servo signal inputs without a shifter.
4.3 Addressable LEDs (WS2812B)
ESP32 Pin 48 ─── DIN
5V ─── VCC
GND ─── GNDTip: Add a 330 ohm resistor on the Data line to prevent voltage spikes.
5. BLE Connectivity Details
If you are debugging connection issues between a Robot and an Apparatus, here are the standard UUIDs used by the Juvantia Protocol:
| Feature | UUID |
|---|---|
| Service | juva0001-0000-1000-8000-00805f9b34fb |
| Device Info | juva0002-0000-1000-8000-00805f9b34fb (READ) |
| Command Char | juva0003-0000-1000-8000-00805f9b34fb (WRITE) |
| Response Char | juva0004-0000-1000-8000-00805f9b34fb (NOTIFY) |
| Menu Char | juva0005-0000-1000-8000-00805f9b34fb (READ) |
| Sync Log Char | juva0006-0000-1000-8000-00805f9b34fb (NOTIFY) |
6. Security Matters
The Secret Key
When you compile the firmware in Fabrica, a unique Secret Key is burned into the binary.
- This key is used to verify HMAC-SHA256 signatures of user tokens.
- Never share your source code/binaries publicly if they contain this key.
- If an Apparatus is compromised physically, delete it in Fabrica and recreate it to generate a new key.
Replay Attacks
The firmware includes a RAM-based nonce cache to prevent a single token from being used multiple times. However, if the apparatus is rebooted, the RAM cache is cleared.
7. Board Strapping Pins
Be careful when connecting buttons or sensors to these pins on boot:
- GPIO 0: Must be HIGH to boot normally.
- GPIO 45/46 (on S3): Used for boot configuration.
Recommendation: Use GPIOs in the middle of the range (e.g., 2, 4, 5, 8, 9) for your basic I/O to avoid boot-time conflicts.