Juvantia Domus: Firmware Configuration & Logic Guide

This document provides a comprehensive specification for creating and configuring Domus units within the Juvantia ecosystem. It is designed to be understood by both humans and AI coding assistants.

---

1. Overview

A Domus is a connectivity-enabled housing system or infrastructure module.

• Hardware: Usually based on ESP32 or ESP32-C3 Super Mini.
• Connectivity: Maintains a persistent encrypted link to the Juvantia Backend via WiFi.
• Discovery: Broadcasts a BLE JUNCTUM beacon, allowing nearby authorized Robuluses to discover and interact with it.

---

2. Theoretical Architecture

When you create a Domus in the Fabrica Garage, you define its "Shared Code" and "Logic Hooks".

The Identity (Step 1)

• ID: Every Domus has a unique ID (e.g., DM-A4X1).
• Secret Key: Used for secure heartbeat and command authentication.

The Protocols (Step 2)

This is where the magic happens. You define:

1. Actions (ID Mapping): A list of interactive commands that will appear in the UI/BLE menu.
2. Shared Code: A C++ snippet (Arduino framework) that runs on the hardware.

---

3. Shared Code Hooks

The Fabrica compiler injects your Shared Code into the base firmware. You can override and implement the following hooks:

void user_setup()

Called once when the device starts. Use this to initialize pins (relays, sensors, LEDs).

void user_setup() {
  pinMode(2, OUTPUT); // Built-in LED or Relay
  digitalWrite(2, LOW);
}

void user_loop()

Called repeatedly. Use this for sensor reading or local logic. Avoid blocking code (long delay()).

void user_loop() {
  // e.g., Read temperature every 10 seconds
}

void on_menu_action(int action_id)

CRITICAL: This function is triggered when an authorized user or robot sends a command.

• action_id: The integer ID you defined in the Actions list in Step 2 of the Garage.

---

4. Actions and ID Mapping

What is an Action?

An Action is a "button" that exists in the digital world (on a user's phone or a robot's logic) but triggers code in the physical world (your Domus hardware).

How to use IDs:

1. In the Fabrica UI, add a Logic Hook.
2. Assign it a Label (e.g., "Open Gate") and an Action ID (integer, e.g., 101).
3. In your Shared Code, use a switch statement inside on_menu_action to handle it.

---

5. Practical Example: Smart Entrance Controller

Suppose you want to control a magnetic lock on Pin 5 and a light on Pin 6.

Action Configuration:

Label	Action ID
Open Entrance	1
Toggle Lights	2

Shared Code Implementation:

#include <Arduino.h>

#define PIN_LOCK 5
#define PIN_LIGHT 6

bool lightState = false;

void user_setup() {
    pinMode(PIN_LOCK, OUTPUT);
    pinMode(PIN_LIGHT, OUTPUT);
    digitalWrite(PIN_LOCK, LOW); // Locked
    digitalWrite(PIN_LIGHT, LOW); // Off
}

void user_loop() {
    // Optional: Auto-lock after 5 seconds if opened
}

void on_menu_action(int action_id) {
    if (action_id == 1) {
        // Open Entrance Logic
        Serial.println("Protocol: Releasing lock...");
        digitalWrite(PIN_LOCK, HIGH);
        delay(2000); 
        digitalWrite(PIN_LOCK, LOW);
        Serial.println("Protocol: Lock secured.");
    } 
    else if (action_id == 2) {
        // Toggle Lights Logic
        lightState = !lightState;
        digitalWrite(PIN_LIGHT, lightState ? HIGH : LOW);
        Serial.println(lightState ? "Lights: ON" : "Lights: OFF");
    }
}

---

6. Pro-Tips for LLMs (Prompts)

If you are asking an AI to generate Shared Code for you, use a prompt like this:

"Generate Juvantia Domus shared code for an ESP32-C3. I need to control a relay on Pin 4. Define an action with ID 10 to pulse the relay for 500ms. Also, blink a status LED on Pin 8 every 2 seconds in the loop."

---

7. Synchronization & Development Flow

1. Draft: Start in the Fabrica Garage.
2. Define: Map your physical pins to Action IDs.
3. Code: Write the logic in the Monaco Editor.
4. Sync: Connect the device via USB and flash the firmware using the Sync step.
5. Connect: Once WiFi is connected, the device will report "Online" and wait for commands.

---