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:

ChipProsRecommended For
ESP32-C3Cheap, Low Power, RISC-VSmall barriers, lights, info-points.
ESP32-S3Powerful, many GPIOsComplex machines with many sensors/actuators.
ESP32 (Original)Tried and trueLegacy 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 Sleep if 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       ───── GND

Most 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          ─── GND

Tip: 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:

FeatureUUID
Servicejuva0001-0000-1000-8000-00805f9b34fb
Device Infojuva0002-0000-1000-8000-00805f9b34fb (READ)
Command Charjuva0003-0000-1000-8000-00805f9b34fb (WRITE)
Response Charjuva0004-0000-1000-8000-00805f9b34fb (NOTIFY)
Menu Charjuva0005-0000-1000-8000-00805f9b34fb (READ)
Sync Log Charjuva0006-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.

apparatus/code_help.md

Maintained by Juvantia Operator