Djubriño

Smart underground garbage container prototype for Arduino UNO Q. This repo combines:

• MCU firmware in sketch/ for sensor sampling, fill estimation, flame detection, and status LEDs
• A Linux-side Python runtime in python/ that talks to the MCU through Bridge, runs camera inference, and syncs with a backend API
• A backend payload contract in smart_garbage_container_api_spec.md

The current app uses the video_objectdetection brick to detect the trash class, merges that with physical sensor data, and reports telemetry and events such as GARBAGE_DETECTED and GARBAGE_CLEARED.

What It Does

• Reads temperature and humidity from a Modulino Thermo
• Reads a simulated load value
• Reads distance from an ultrasonic sensor to estimate fill level
• Reads a KY-026 flame sensor on A2
• Fuses ultrasonic + weight inputs into a fill percentage and fill state
• Drives an RGB status LED based on fill state, flame state, and faults
• Polls the MCU from Linux using Arduino_RouterBridge
• Runs vision inference with VideoObjectDetection
• Queues telemetry, heartbeat, config acknowledgements, and events for backend upload
• Persists identity/config and an offline outbox locally

Architecture

Sensors + LED <-> Arduino UNO Q firmware <-> Bridge <-> Python runtime
                                                    |
                                                    +-> VideoObjectDetection
                                                    |
                                                    +-> REST backend API

MCU side

The firmware in sketch/sketch.ino samples sensors, computes fill state, tracks health, and exposes bridge methods such as:

• get_sensor_sample()
• get_health()
• set_fill_calibration(...)
• set_flame_threshold_pct(...)
• set_simulated_mode(...)
• set_rgb_state(...)

More wiring and firmware details are in sketch/README.md.

Linux/Python side

The runtime in python/main.py is responsible for:

• bootstrapping the device with the backend using a claim code
• polling the MCU every 500 ms for compact sensor snapshots
• batching telemetry and queueing heartbeats
• pulling remote config revisions
• detecting stationary trash in camera frames
• creating GARBAGE_DETECTED and GARBAGE_CLEARED events
• uploading event images when enabled
• retrying failed uploads from a persistent outbox

Persistent local files:

• python/device_state.json: saved identity, token, config revision, and config
• python/device_outbox.json: queued messages for offline retry

Hardware

Required hardware for the current prototype:

• Arduino UNO Q
• Modulino Thermo
• Modulino Light
• Ultrasonic sensor
• KY-026 flame sensor
• Potentiometer on A0 for load simulation
• RGB LED
• USB camera for vision inference

Key wiring from the firmware docs:

Component	Pin
Flame sensor AO	A1
Ultrasonic TRIG	D2
Ultrasonic ECHO	D7
RGB LED red	D3
RGB LED green	D5
RGB LED blue	D6
Modulino devices	Wire1 / Modulino bus

Repo Layout

app.yaml                         Arduino App Lab app definition
python/main.py                   Linux-side runtime and backend sync
sketch/sketch.ino               MCU firmware entrypoint
sketch/bridge/                  Bridge API exposed by the MCU
sketch/sensors/                 Sensor drivers
sketch/logic/                   Fill estimation, health, calibration
sketch/output/                  RGB LED behavior
smart_garbage_container_api_spec.md

Running It

Arduino App Lab

1. Open the project in Arduino App Lab.
2. Target Arduino UNO Q.
3. Keep sketch/sketch.yaml as the active sketch profile.
4. Make sure the USB camera is available to the Linux-side app runtime.
5. Run the app.

The sketch profile currently depends on:

• Arduino_RouterBridge
• Arduino_Modulino

Environment

The Python runtime loads environment variables from .env if present.

Minimum useful variables:

SMART_WASTE_API_BASE_URL=http://your-backend-host:8080
SMART_WASTE_CLAIM_CODE=YOUR-CLAIM-CODE

Useful optional variables:

• SMART_WASTE_MODEL_ID
• SMART_WASTE_LINUX_APP_VERSION
• SMART_WASTE_MCU_VERSION
• SMART_WASTE_CAMERA_FAULT_TIMEOUT_SEC
• SMART_WASTE_SAVE_MCU_CALIBRATION
• SMART_WASTE_GARBAGE_STALE_CLEAR_SEC

If SMART_WASTE_API_BASE_URL or SMART_WASTE_CLAIM_CODE is missing, the app still runs locally but skips backend bootstrap and sync.

Backend Flow

On startup, the Python runtime can:

1. POST /api/v1/device/bootstrap
2. persist the returned device_id, container_id, token, and config
3. queue periodic telemetry to /api/v1/device/telemetry
4. queue heartbeats to /api/v1/device/heartbeat
5. poll /api/v1/device/config
6. post events to /api/v1/device/events
7. upload event media to /api/v1/device/events/{event_id}/media

The full contract lives in smart_garbage_container_api_spec.md.

Vision Logic

The camera side does more than simple one-frame detection:

• it looks for the trash class
• keeps a rolling window of detections
• requires a configurable number of positive frames
• checks whether the detected object is stationary
• clears stale detections when the scene returns to normal

This helps reduce false positives from brief motion near the container.

Notes

• light_raw_adc is kept in payloads for compatibility even though the source is the Modulino light reading.
• Event image upload is optional and controlled by config.