Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/AngelAmoSanchez/TFG-RaspberryPi-BLE/llms.txt

Use this file to discover all available pages before exploring further.

The agent reads all configuration from a .env file (or from actual environment variables) at startup. The load_config_from_file function in src/config.py calls python-dotenv to load the file and then validates every value before the agent starts. If any required variable is missing or invalid the process exits with a descriptive error.

​
Complete .env example

The file below is drawn directly from .env.example in the repository. Copy it to .env and fill in the values for your deployment.
.env
# Device identity
DEVICE_ID=rpi-001
DEVICE_NAME=
DEVICE_LOCATION=ETSII, Sevilla

# Communication backend
COMMUNICATION_MODE=mqtt         # mqtt | http

# Logging
LOG_LEVEL=INFO

# ── MQTT (used when COMMUNICATION_MODE=mqtt) ──────────────────────
MQTT_BROKER=.eu-central-1.emqxsl.com
MQTT_PORT=8883
MQTT_TOPIC=
MQTT_USERNAME=
MQTT_PASSWORD=
MQTT_BUFFER_SIZE=100

# ── HTTP (used when COMMUNICATION_MODE=http) ──────────────────────
HTTP_BASE_URL=http://localhost:8000
HTTP_API_KEY=
HTTP_TIMEOUT=10

# ── BLE scanner ───────────────────────────────────────────────────
SCAN_DURATION=10
SCAN_INTERVAL=30
NEAR_THRESHOLD=-60
MEDIUM_THRESHOLD=-75
USE_MOCK_SCANNER=false

​
Device identity

​
env.DEVICE_ID
string
required
Unique identifier for this Raspberry Pi. Included in every published message so the backend can distinguish between multiple counters. Must be at least three characters long.Example: rpi-entrance-01
​
env.DEVICE_NAME
string
Human-readable label for the device. Optional. When set it is forwarded as name in the published payload.Example: Main entrance counter
​
env.DEVICE_LOCATION
string
Physical location description. Optional. When set it is forwarded as location in the published payload.Example: ETSII, Sevilla

​
Communication mode

​
env.COMMUNICATION_MODE
string
default:"mqtt"
required
Selects the transport used to send detection data to the backend. Accepted values: mqtt or http. The agent validates this at startup and raises a ValueError for any other value.
Used when COMMUNICATION_MODE=mqtt. The agent connects to the broker with paho-mqtt, publishes detection batches at QoS 1, and buffers messages locally when offline.
​
env.MQTT_BROKER
string
default:"broker.emqx.io"
Hostname or IP of the MQTT broker.Example: abc123.eu-central-1.emqxsl.com
​
env.MQTT_PORT
number
default:"1883"
TCP port for the broker connection. Use 8883 for TLS. When port 8883 is set the client enables TLS automatically.
​
env.MQTT_TOPIC
string
default:"tfg/detections/raw"
Topic to publish detection messages to.Example: building/floor1/detections
​
env.MQTT_USERNAME
string
MQTT broker username. Optional for open brokers; required for authenticated deployments.
​
env.MQTT_PASSWORD
string
MQTT broker password. Optional for open brokers.
​
env.MQTT_BUFFER_SIZE
number
default:"100"
Maximum number of detection batches to hold in the in-memory buffer while the broker is unreachable. When the buffer is full the oldest message is dropped to make room for the newest. Set to 0 to disable buffering.
If MQTT_BROKER is missing or left as the default broker.emqx.io, the agent logs a warning and switches to MockMQTTClient, which prints detections locally instead of sending them over the network.

​
BLE scanner

​
env.SCAN_DURATION
number
default:"10"
How many seconds each passive BLE scan lasts. Valid range: 1–60 seconds. Longer scans detect more devices but reduce the reporting frequency.
​
env.SCAN_INTERVAL
number
default:"30"
Seconds to wait between the end of one scan and the start of the next. Must be at least 5 seconds.
​
env.NEAR_THRESHOLD
number
default:"-60"
RSSI boundary (dBm) above which a device is classified as NEAR. Must be a negative integer. Devices with RSSI ≥ this value fall in the near zone (roughly 0–2 m).
​
env.MEDIUM_THRESHOLD
number
default:"-75"
RSSI boundary (dBm) above which a device is classified as MEDIUM. Must be less than NEAR_THRESHOLD. Devices between this value and NEAR_THRESHOLD fall in the medium zone (roughly 2–5 m). All others are FAR.
​
env.USE_MOCK_SCANNER
boolean
default:"false"
When set to true the agent uses MockBLEScanner instead of the real Bleak-based scanner. The mock generates a randomised set of up to 8 simulated devices each cycle, which is useful for development and CI environments that have no Bluetooth hardware.

​
Logging

​
env.LOG_LEVEL
string
default:"INFO"
Python logging level applied to the root logger. Accepted values: DEBUG, INFO, WARNING, ERROR, CRITICAL. Use DEBUG to see per-device RSSI lines in the log output.
Log output goes to both stdout (captured by journalctl) and the rotating file ./logs/iot-agent.log. The file rotates at 5 MB and keeps up to three backups.

Build docs developers (and LLMs) love

Get started for freeTalk to us