{"id":41234105,"url":"https://github.com/hyperpolymath/the-hotchocolabot","last_synced_at":"2026-01-23T01:00:21.611Z","repository":{"id":325693524,"uuid":"1101584159","full_name":"hyperpolymath/the-hotchocolabot","owner":"hyperpolymath","description":"An Educational Robotics Platform for Teaching Reverse Engineering and Systems Thinking","archived":false,"fork":false,"pushed_at":"2026-01-10T13:51:33.000Z","size":190,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-11T04:07:49.900Z","etag":null,"topics":["automation","hyperpolymath-tools","integration","my-coolest-projects","operations","reliability","rhodium-standard","rsr","systems","tooling"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyperpolymath.png","metadata":{"files":{"readme":"README.adoc","changelog":"CHANGELOG.adoc","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":"MAINTAINERS.md","copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"hyperpolymath","ko_fi":"hyperpolymath","liberapay":"hyperpolymath"}},"created_at":"2025-11-21T22:20:48.000Z","updated_at":"2026-01-10T13:51:36.000Z","dependencies_parsed_at":"2025-12-29T12:10:52.562Z","dependency_job_id":null,"html_url":"https://github.com/hyperpolymath/the-hotchocolabot","commit_stats":null,"previous_names":["hyperpolymath/the-hotchocolabot"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/hyperpolymath/the-hotchocolabot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperpolymath%2Fthe-hotchocolabot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperpolymath%2Fthe-hotchocolabot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperpolymath%2Fthe-hotchocolabot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperpolymath%2Fthe-hotchocolabot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperpolymath","download_url":"https://codeload.github.com/hyperpolymath/the-hotchocolabot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperpolymath%2Fthe-hotchocolabot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28676439,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-22T20:48:19.482Z","status":"ssl_error","status_checked_at":"2026-01-22T20:48:14.968Z","response_time":144,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","hyperpolymath-tools","integration","my-coolest-projects","operations","reliability","rhodium-standard","rsr","systems","tooling"],"created_at":"2026-01-23T01:00:19.704Z","updated_at":"2026-01-23T01:00:21.543Z","avatar_url":"https://github.com/hyperpolymath.png","language":"Rust","funding_links":["https://github.com/sponsors/hyperpolymath","https://ko-fi.com/hyperpolymath","https://liberapay.com/hyperpolymath"],"categories":[],"sub_categories":[],"readme":"= HotChocolaBot\n\nimage:[Palimpsest-MPL-1.0,link=\"https://github.com/hyperpolymath/palimpsest-license\"]\n\n*An Educational Robotics Platform for Teaching Reverse Engineering and Systems Thinking*\n\n[![RSR Bronze](https://img.shields.io/badge/RSR-Bronze-cd7f32?style=flat-square)](RSR_COMPLIANCE.md)\n[![CI](https://img.shields.io/github/actions/workflow/status/Hyperpolymath/the-hotchocolabot/rust_ci.yml?style=flat-square)](https://github.com/Hyperpolymath/the-hotchocolabot/actions)\n\nPart of UAL Creative Communities' Postdisciplinary Mechatronics Group (MechCC)\n\n== Overview\n\nHotChocolaBot is an over-engineered hot chocolate dispenser designed to teach reverse engineering, systems thinking, and problem-solving skills through heutagogic (self-directed) learning. Students deconstruct and analyze the system to understand complex engineering principles in an engaging, hands-on environment.\n\n=== Why Over-Engineered?\n\nThe deliberate complexity serves pedagogical purposes:\n- *Layered Learning*: Multiple levels of abstraction (hardware, firmware, safety systems)\n- *Real-World Complexity*: Mirrors professional engineering projects\n- *Discovery-Based*: Students uncover design decisions through investigation\n- *Safety-First*: Demonstrates formal verification and CNO (Certified Null Operations) principles\n\n== Features\n\n- *Rust-Based Control System*: Memory-safe, formally verifiable control logic\n- *Hardware Abstraction Layer*: Trait-based design enables testing without physical hardware\n- *Safety Monitoring*: State machine-based safety system with emergency stop\n- *Educational Mode*: Configurable delays and system introspection for learning\n- *Three-Ingredient System*: Cocoa, milk, and sugar with programmable recipes\n- *Mock Hardware*: Full simulation for development without Raspberry Pi\n- *RSR Compliant*: Bronze level (Rhodium Standard Repository), targeting Silver ([details](RSR_COMPLIANCE.md))\n\n== Hardware Requirements\n\n=== Minimum Setup\n\n- Raspberry Pi 4 (2GB+ RAM recommended)\n- 3× Peristaltic pumps (12V DC)\n- 3× Relay modules (or MOSFET drivers)\n- Temperature sensor (TMP102 or DS18B20)\n- 16×2 LCD with I2C backpack\n- Emergency stop button\n- Status LED\n- 12V power supply (2A+)\n- Wiring, breadboard, connectors\n\n*Estimated Cost*: £500-750 (See `hardware/bom/parts_list.md` for detailed BOM)\n\n=== GPIO Pin Assignments (BCM Numbering)\n\n| Component | Default Pin |\n|-----------|-------------|\n| Cocoa Pump | GPIO 17 |\n| Milk Pump | GPIO 27 |\n| Sugar Pump | GPIO 22 |\n| Emergency Stop | GPIO 23 |\n| Status LED | GPIO 24 |\n| Temperature Sensor | I2C (0x48) |\n| LCD Display | I2C (0x27) |\n\n== Software Setup\n\n=== Prerequisites\n\n- Rust 1.70+ (`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`)\n- Git\n\n=== Installation\n\n```bash\n= Clone repository\n\nimage:https://img.shields.io/badge/license-Palimpsest--MPL--1.0-purple.svg[Palimpsest-MPL-1.0,link=\"https://github.com/hyperpolymath/palimpsest-license\"] image:https://img.shields.io/badge/philosophy-Palimpsest-purple.svg[Palimpsest,link=\"https://github.com/hyperpolymath/palimpsest-licence\"]\ngit clone https://github.com/Hyperpolymath/the-hotchocolabot.git\ncd the-hotchocolabot\n\n= Copy configuration template\n\nimage:https://img.shields.io/badge/license-Palimpsest--MPL--1.0-purple.svg[Palimpsest-MPL-1.0,link=\"https://github.com/hyperpolymath/palimpsest-license\"] image:https://img.shields.io/badge/philosophy-Palimpsest-purple.svg[Palimpsest,link=\"https://github.com/hyperpolymath/palimpsest-licence\"]\ncp config.toml.example config.toml\n\n= Edit configuration for your hardware\n\nimage:https://img.shields.io/badge/license-Palimpsest--MPL--1.0-purple.svg[Palimpsest-MPL-1.0,link=\"https://github.com/hyperpolymath/palimpsest-license\"] image:https://img.shields.io/badge/philosophy-Palimpsest-purple.svg[Palimpsest,link=\"https://github.com/hyperpolymath/palimpsest-licence\"]\nnano config.toml\n\n= Build (development mode with mock hardware)\n\nimage:https://img.shields.io/badge/license-Palimpsest--MPL--1.0-purple.svg[Palimpsest-MPL-1.0,link=\"https://github.com/hyperpolymath/palimpsest-license\"] image:https://img.shields.io/badge/philosophy-Palimpsest-purple.svg[Palimpsest,link=\"https://github.com/hyperpolymath/palimpsest-licence\"]\ncargo build\n\n= Build for Raspberry Pi (cross-compile or on-device)\n\nimage:https://img.shields.io/badge/license-Palimpsest--MPL--1.0-purple.svg[Palimpsest-MPL-1.0,link=\"https://github.com/hyperpolymath/palimpsest-license\"] image:https://img.shields.io/badge/philosophy-Palimpsest-purple.svg[Palimpsest,link=\"https://github.com/hyperpolymath/palimpsest-licence\"]\ncargo build --release\n\n= Run tests\n\nimage:https://img.shields.io/badge/license-Palimpsest--MPL--1.0-purple.svg[Palimpsest-MPL-1.0,link=\"https://github.com/hyperpolymath/palimpsest-license\"] image:https://img.shields.io/badge/philosophy-Palimpsest-purple.svg[Palimpsest,link=\"https://github.com/hyperpolymath/palimpsest-licence\"]\ncargo test\n\n= Run with mock hardware (for development)\n\nimage:https://img.shields.io/badge/license-Palimpsest--MPL--1.0-purple.svg[Palimpsest-MPL-1.0,link=\"https://github.com/hyperpolymath/palimpsest-license\"] image:https://img.shields.io/badge/philosophy-Palimpsest-purple.svg[Palimpsest,link=\"https://github.com/hyperpolymath/palimpsest-licence\"]\ncargo run\n\n= Run on Raspberry Pi\n\nimage:https://img.shields.io/badge/license-Palimpsest--MPL--1.0-purple.svg[Palimpsest-MPL-1.0,link=\"https://github.com/hyperpolymath/palimpsest-license\"] image:https://img.shields.io/badge/philosophy-Palimpsest-purple.svg[Palimpsest,link=\"https://github.com/hyperpolymath/palimpsest-licence\"]\nsudo cargo run --release\n```\n\n=== Cross-Compilation for Raspberry Pi\n\n```bash\n= Install cross-compilation toolchain\n\nimage:https://img.shields.io/badge/license-Palimpsest--MPL--1.0-purple.svg[Palimpsest-MPL-1.0,link=\"https://github.com/hyperpolymath/palimpsest-license\"] image:https://img.shields.io/badge/philosophy-Palimpsest-purple.svg[Palimpsest,link=\"https://github.com/hyperpolymath/palimpsest-licence\"]\nrustup target add armv7-unknown-linux-gnueabihf\n\n= Install cross-compilation dependencies\n\nimage:https://img.shields.io/badge/license-Palimpsest--MPL--1.0-purple.svg[Palimpsest-MPL-1.0,link=\"https://github.com/hyperpolymath/palimpsest-license\"] image:https://img.shields.io/badge/philosophy-Palimpsest-purple.svg[Palimpsest,link=\"https://github.com/hyperpolymath/palimpsest-licence\"]\ncargo install cross\n\n= Build for Raspberry Pi\n\nimage:https://img.shields.io/badge/license-Palimpsest--MPL--1.0-purple.svg[Palimpsest-MPL-1.0,link=\"https://github.com/hyperpolymath/palimpsest-license\"] image:https://img.shields.io/badge/philosophy-Palimpsest-purple.svg[Palimpsest,link=\"https://github.com/hyperpolymath/palimpsest-licence\"]\ncross build --target armv7-unknown-linux-gnueabihf --release\n\n= Copy to Raspberry Pi\n\nimage:https://img.shields.io/badge/license-Palimpsest--MPL--1.0-purple.svg[Palimpsest-MPL-1.0,link=\"https://github.com/hyperpolymath/palimpsest-license\"] image:https://img.shields.io/badge/philosophy-Palimpsest-purple.svg[Palimpsest,link=\"https://github.com/hyperpolymath/palimpsest-licence\"]\nscp target/armv7-unknown-linux-gnueabihf/release/hotchocolabot pi@raspberrypi.local:~/\n```\n\n== Architecture\n\n=== System Components\n\n```\n┌─────────────────────────────────────────┐\n│         Main Controller                 │\n│  (src/control/mod.rs)                   │\n└─────────────────┬───────────────────────┘\n                  │\n        ┌─────────┴──────────┐\n        │                    │\n┌───────▼────────┐  ┌────────▼─────────┐\n│ Safety Monitor │  │ Hardware Layer   │\n│ (src/safety)   │  │ (src/hardware)   │\n│                │  │                  │\n│ • State Machine│  │ • Pumps (GPIO)   │\n│ • CNO Checks   │  │ • Sensors (I2C)  │\n│ • Temp Limits  │  │ • Display (I2C)  │\n│ • E-Stop       │  │ • Mock Impl.     │\n└────────────────┘  └──────────────────┘\n                           │\n                    ┌──────┴────────┐\n                    │  Raspberry Pi │\n                    │  GPIO / I2C   │\n                    └───────────────┘\n```\n\n=== Code Organization\n\n```\nthe-hotchocolabot/\n├── src/\n│   ├── main.rs              # Entry point\n│   ├── config/              # Configuration management\n│   ├── control/             # Main control logic\n│   ├── hardware/            # Hardware abstraction\n│   │   ├── mod.rs           # Trait definitions\n│   │   ├── pump.rs          # GPIO pump control\n│   │   ├── sensor.rs        # I2C temperature sensor\n│   │   ├── display.rs       # I2C LCD display\n│   │   └── mock.rs          # Mock implementations\n│   └── safety/              # Safety monitoring\n├── tests/                   # Integration tests\n├── hardware/                # Hardware documentation\n│   ├── bom/                 # Bill of materials\n│   ├── schematics/          # Wiring diagrams\n│   └── assembly/            # Assembly instructions\n├── education/               # Educational materials\n│   ├── workshops/           # Workshop curricula\n│   ├── assessments/         # Pre/post assessments\n│   └── activities/          # Student activity sheets\n└── docs/                    # Documentation\n    ├── technical/           # Technical specifications\n    ├── research/            # Research connections\n    └── competition/         # Competition materials\n```\n\n== Educational Use\n\n=== Workshop Format\n\nHotChocolaBot is designed for 2-3 hour workshops with students aged 12-18:\n\n1. *Introduction* (30 min): Present the \"mystery box\" - what does it do?\n2. *Exploration* (45 min): Students observe, hypothesize, diagram\n3. *Deconstruction* (45 min): Guided hardware/software investigation\n4. *Reconstruction* (30 min): Students propose improvements\n5. *Reflection* (15 min): Systems thinking discussion\n\n=== Learning Outcomes\n\n- Reverse engineering methodology\n- Systems thinking and component interaction\n- Safety-critical system design\n- State machines and formal verification concepts\n- Hardware-software integration\n- Professional engineering practices\n\n=== Customization\n\nEdit `config.toml` to enable educational features:\n\n```toml\n[education]\nchallenge_mode = true           # Hide labels, make students discover\nshow_internals = true           # Display system state on LCD\nenable_teaching_failures = true # Intentional failures for learning\nobservation_delay_ms = 1000     # Slow down for observation\n```\n\n== Safety\n\n=== Built-In Safety Features\n\n- *Temperature Monitoring*: Continuous temperature validation\n- *Pump Runtime Limits*: Maximum runtime prevents overflow\n- *Emergency Stop*: Hardware button for immediate shutdown\n- *State Machine Verification*: Formal state transitions\n- *CNO Principles*: Certified Null Operations for safety-critical code\n\n=== Safety Configuration\n\n```toml\n[safety]\nmax_temperature = 90.0      # Celsius\nmin_temperature = 5.0       # Celsius\nmax_pump_runtime = 30       # Seconds\noperation_timeout = 120     # Seconds\nemergency_stop_enabled = true\n```\n\n=== Important Safety Notes\n\n⚠️ *Never operate unattended*\n⚠️ *Ensure emergency stop is accessible*\n⚠️ *Regularly inspect pumps and connections*\n⚠️ *Use food-safe tubing for ingredients*\n⚠️ *Supervise students during operation*\n\n== Research Connections\n\nHotChocolaBot demonstrates concepts from ongoing research:\n\n- *Phase-Separated Approach*: Oblíbený's methodology for systems design\n- *CNO (Certified Null Operations)*: Safety verification principles\n- *UPM (Universal Project Manager)*: Case study for project management theory\n- *Formal Verification*: State machine approach bridges theory to practice\n\n== Competition Submission\n\n=== Target: Robotics for Good Youth Challenge 2025-2026\n\n- *Deadline*: April 1, 2026\n- *Theme*: Food security (adapted to educational food systems)\n- *Requirements*:\n  - Working prototype ✓\n  - Video demonstration\n  - Workshop delivery (3+ sessions, 15+ students)\n  - Impact metrics and assessment data\n  - Open-source repository ✓\n\n=== Alternative Competitions\n\n- FIRST Tech Challenge Educational Outreach Award\n- ECER (Academic paper on educational methodology)\n\n== Development Status\n\n- [x] Repository structure\n- [x] Rust control system scaffolding\n- [x] Hardware abstraction layer\n- [x] Mock implementations for testing\n- [x] Safety monitoring system\n- [ ] Complete hardware assembly\n- [ ] Workshop curriculum finalization\n- [ ] Pilot workshops (3 sessions)\n- [ ] Impact assessment collection\n- [ ] Competition submission\n\n== Contributing\n\nSee `CONTRIBUTING.md` for development guidelines.\n\n=== Quick Start for Developers\n\n```bash\n= Run tests\n\nimage:https://img.shields.io/badge/license-Palimpsest--MPL--1.0-purple.svg[Palimpsest-MPL-1.0,link=\"https://github.com/hyperpolymath/palimpsest-license\"] image:https://img.shields.io/badge/philosophy-Palimpsest-purple.svg[Palimpsest,link=\"https://github.com/hyperpolymath/palimpsest-licence\"]\ncargo test\n\n= Run with logging\n\nimage:https://img.shields.io/badge/license-Palimpsest--MPL--1.0-purple.svg[Palimpsest-MPL-1.0,link=\"https://github.com/hyperpolymath/palimpsest-license\"] image:https://img.shields.io/badge/philosophy-Palimpsest-purple.svg[Palimpsest,link=\"https://github.com/hyperpolymath/palimpsest-licence\"]\nRUST_LOG=debug cargo run\n\n= Format code\n\nimage:https://img.shields.io/badge/license-Palimpsest--MPL--1.0-purple.svg[Palimpsest-MPL-1.0,link=\"https://github.com/hyperpolymath/palimpsest-license\"] image:https://img.shields.io/badge/philosophy-Palimpsest-purple.svg[Palimpsest,link=\"https://github.com/hyperpolymath/palimpsest-licence\"]\ncargo fmt\n\n= Lint\n\nimage:https://img.shields.io/badge/license-Palimpsest--MPL--1.0-purple.svg[Palimpsest-MPL-1.0,link=\"https://github.com/hyperpolymath/palimpsest-license\"] image:https://img.shields.io/badge/philosophy-Palimpsest-purple.svg[Palimpsest,link=\"https://github.com/hyperpolymath/palimpsest-licence\"]\ncargo clippy\n\n= Benchmark\n\nimage:https://img.shields.io/badge/license-Palimpsest--MPL--1.0-purple.svg[Palimpsest-MPL-1.0,link=\"https://github.com/hyperpolymath/palimpsest-license\"] image:https://img.shields.io/badge/philosophy-Palimpsest-purple.svg[Palimpsest,link=\"https://github.com/hyperpolymath/palimpsest-licence\"]\ncargo bench\n```\n\n== License\n\nDual-licensed under MIT OR Apache-2.0. See `LICENSE-MIT` and `LICENSE-APACHE` for details.\n\n== Acknowledgments\n\n- UAL Creative Communities - MechCC\n- Robotics for Good Youth Challenge (ITU/FAO)\n- Rust Embedded Working Group\n- Open-source hardware community\n\n== Contact\n\n- Repository: https://github.com/Hyperpolymath/the-hotchocolabot\n- Issues: https://github.com/Hyperpolymath/the-hotchocolabot/issues\n\n---\n\n*Built with ❤️ for education and open-source learning*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperpolymath%2Fthe-hotchocolabot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperpolymath%2Fthe-hotchocolabot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperpolymath%2Fthe-hotchocolabot/lists"}