HotelMind — Embedded IoT & Edge Computing for Smart Hotel Rooms

AI-Assisted Smart Hotel Room Control Panel — TEKNOFEST 2025 Tourism Technologies

🏆 3rd Place, TEKNOFEST 2025 — Tourism Technologies (Turizm Teknolojileri), "User Experience & Micro-Applications" track. Team HotelMind (ID 585569).

---

What this repository is

HotelMind turns a hotel room into a sensored, remotely controllable edge node: a Raspberry Pi reads the room (temperature, pressure, gas, occupancy, keycard), drives the room (climate relays, IR-controlled TV/AC, alarm, lights), mints its own door-access tokens, and keeps a secure MQTT link to an AWS backend that stores history and runs AI automation.

This repository is organised electronics-first. The edge/ tree — the embedded firmware and the edge-computing layer — is the headline. The cloud backend and the Flutter dashboard live under infrastructure/ because that is what they are here: supporting infrastructure around the device.

hotelmind/
├── edge/                  ⭐ Embedded firmware & edge computing  (Raspberry Pi)
│   ├── src/               Python edge agent — drivers, net, security, core
│   ├── docs/              Hardware BOM & wiring, protocols, roadmap
│   ├── config/            secrets.example.json
│   └── vendor/            Vendored aws-iot-device-sdk-python-v2
│
├── infrastructure/        Supporting layers
│   ├── cloud/             AWS Amplify Gen 2 — Lambda, AppSync, DynamoDB, IoT Core rules
│   └── app/               Flutter web dashboard
│
├── schematics/            Electronic connection schematic (bring-up wiring reference)
└── docs/
    ├── diagrams/          SVG diagrams used in this README
    ├── figures/           System-level figures from the project report
    └── media/             Stills from the demo video

---

The edge node — edge/

A headless Python agent (edge/src/main.py) for a Raspberry Pi 4. Hardware is auto-detected; with no RPi.GPIO / smbus2 present every driver falls back to a simulation path, so the exact same code runs on a laptop.

cd edge
pip install -r requirements.txt
python src/main.py --mock --verbose     # runs anywhere, all hardware simulated

Sensor drivers — written at the register / protocol level

Sensor	Interface	What the driver does	File
BMP280 temp / pressure	I²C (smbus2, addr 0x76)	Hand-coded register map, reads the 24-byte factory calibration blob, runs the Bosch fixed-point compensation formulas with integer bit-shift math, ×16 oversampling	drivers/sensors/bmp280.py
HC-SR04 ultrasonic	Bit-banged GPIO	10 µs trigger, software echo pulse-width timing with 100 ms guard timeouts, speed-of-sound distance, 2–400 cm clamp, distance→occupancy	drivers/sensors/hcsr04.py
MQ-2 gas	Digital GPIO	Active-low logic, 0–10 level, is_gas_detected() trips the alarm path	drivers/sensors/mq2.py
RC522 RFID	SPI	Keycard-presence reader (driver stub — see roadmap)	drivers/sensors/rc522.py

Actuator drivers

Actuator	Interface	Notes	File
IR blaster	Bit-banged raw pulse trains	Walks a µs-timing array toggling the GPIO pin; NEC-style frames in ir_codes.json (TV/AC power, volume, temp)	drivers/actuators/ir_blaster.py
Climate	Relay / GPIO	Closed-loop with hysteresis — ±1.5 °C / ±5 % dead-bands so relays don't chatter	drivers/actuators/climate.py
Alarm	Hardware PWM	Alternating 1 kHz / 500 Hz beep pattern for gas / security events	drivers/actuators/alarm.py

Edge ↔ cloud & on-device security

• net/mqtt_client.py — AWS IoT Core over MQTT with mutual TLS (X.509, port 8883, aws-iot-device-sdk-python-v2), a structured room/<id>/… topic namespace, UUID request/response correlation, QoS 1, and on-device ring buffers (last 99 samples/events) for reconnect backfill.
• security/access_token.py — the device pulls a per-room key over MQTT, then locally mints HMAC-SHA256-signed, time-bound QR tokens (3 h validity, 4 min rotation) on a Tkinter kiosk. The cloud verify-qr Lambda validates. Token minting survives a brief uplink outage.

📖 Deep dives: edge/docs/hardware.md · edge/docs/protocols.md · edge/docs/roadmap.md (electronics / firmware / edge-computing backlog) · schematics/ (wiring)

---

Hardware & wiring — schematics/

Assembled prototype (annotated) and the matching connection schematic:

BOM, GPIO pin map and bring-up notes: edge/docs/hardware.md.

---

Supporting infrastructure — infrastructure/

• infrastructure/cloud/ — AWS Amplify Gen 2. IoT Core rules → Lambda (ai-agent, verify-qr, secret-key, sensor/event/room-control resolvers) → DynamoDB (SensorData, RoomEvent, UserPreference, QrSession); AppSync GraphQL + real-time subscriptions.
• infrastructure/app/ — Flutter web dashboard (flutter run -d chrome): dashboard, QR scanner, settings, event log; live updates via AppSync subscriptions, charts via fl_chart.

Data pipeline: sensors sampled every ~2 s → calibrate/preprocess on device → MQTT publish → IoT Rule triggers Lambda → AI evaluation → commands returned over MQTT → persisted to DynamoDB → dashboard updates.

---

Demo

59-second walkthrough — dashboard, live sensor cards, QR room access from a phone, and RFID keycard entry, all against the physical board.

▶️ youtube.com/watch?v=3_U6osKFhtw

Room controls	RFID keycard access	The board

---

Getting started

Edge agent (see above) — Python 3.9+; on the Pi enable I²C/SPI via raspi-config and install RPi.GPIO + smbus2. Put your AWS IoT certs in edge/certs/ and copy edge/config/secrets.example.json → edge/config/secrets.json.

Cloud backend: cd infrastructure/cloud && npm install && npx ampx sandbox

Dashboard: cd infrastructure/app && flutter pub get && flutter run -d chrome

---

Team & credits

TEKNOFEST 2025 Tourism Technologies — Team HotelMind:

Member	Role
Cem Girgin	Electronics & embedded lead (Electrical & Electronics Engineering) — circuit design and hardware bring-up (sensor/actuator wiring, GPIO / I²C / SPI, level-shifting, relay/mains side); the Raspberry Pi edge agent and its from-scratch drivers (BMP280 register-level I²C, bit-banged HC-SR04, MQ-2, IR pulse-train blaster, PWM alarm, hysteresis climate loop); the MQTT-over-mTLS client and topic design; and the on-device HMAC-signed access-token generator. Also team lead — planning, coordination, schedule & budget.
Mustafa Yavuz Okumuş	AI-agent engineer — cloud automation logic and AI integration; original code repository / graduation capstone (Mathematics & Computer Science)

The original repository was developed by Mustafa Yavuz Okumuş as a graduation capstone at Istanbul Kültür University; the accompanying thesis compares cloud providers (AWS / Azure / GCP) and service models (IaaS / PaaS / SaaS) for IoT ecosystems.

• 📄 Academic article & presentation: https://sc-riber.com/projects/hotelmind
• 🎥 Project demo video: https://www.youtube.com/watch?v=3_U6osKFhtw

License

MIT