{"id":14986600,"url":"https://github.com/genielabs/homegenie-mini","last_synced_at":"2025-04-11T20:32:22.894Z","repository":{"id":78129582,"uuid":"167666905","full_name":"genielabs/homegenie-mini","owner":"genielabs","description":"Programmable smart device for smart homes, IoT applications,  wearable devices, robotics and more...","archived":false,"fork":false,"pushed_at":"2025-04-03T21:11:07.000Z","size":5573,"stargazers_count":12,"open_issues_count":0,"forks_count":5,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-03T22:23:45.989Z","etag":null,"topics":["arduino","automation","building-automation","esp32","esp32-arduino","esp8266","esp8266-arduino","firmware","health-monitoring","homegenie","homegenie-api","iot-device","open-api","robotics","smart-device","smart-home","smart-light","smart-shutters","transceiver","wearable-devices"],"latest_commit_sha":null,"homepage":"https://homegenie.it","language":"C","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/genielabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-26T08:29:09.000Z","updated_at":"2025-04-03T21:11:12.000Z","dependencies_parsed_at":"2024-01-11T04:37:35.148Z","dependency_job_id":"890ed21c-85d1-4c3a-ac93-c4efb7fc8dc7","html_url":"https://github.com/genielabs/homegenie-mini","commit_stats":{"total_commits":128,"total_committers":2,"mean_commits":64.0,"dds":0.1015625,"last_synced_commit":"875dc2760ddc06bd19be1b61d80b79c5b9658244"},"previous_names":[],"tags_count":62,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/genielabs%2Fhomegenie-mini","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/genielabs%2Fhomegenie-mini/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/genielabs%2Fhomegenie-mini/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/genielabs%2Fhomegenie-mini/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/genielabs","download_url":"https://codeload.github.com/genielabs/homegenie-mini/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248476472,"owners_count":21110291,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["arduino","automation","building-automation","esp32","esp32-arduino","esp8266","esp8266-arduino","firmware","health-monitoring","homegenie","homegenie-api","iot-device","open-api","robotics","smart-device","smart-home","smart-light","smart-shutters","transceiver","wearable-devices"],"created_at":"2024-09-24T14:13:12.499Z","updated_at":"2025-04-11T20:32:17.883Z","avatar_url":"https://github.com/genielabs.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"![homegenie-mini workflow](https://github.com/genielabs/homegenie-mini/actions/workflows/platformio.yml/badge.svg)\n\n# HomeGenie Mini v1.2 \u003csmall\u003e`ESP32 / ESP8266`\u003c/small\u003e\n\nHomeGenie mini *(code name **Sbirulino**)* is an **open source library** for building custom firmware for smart devices\nbased on *ESP32* or *ESP8266* SoC.\n\nhttps://homegenie.it/mini\n\n\n## Features\n\n- Easy device configuration using Wi-Fi protected setup button (WPS) or Bluetooth\n- Does not require an Internet connection to be configured or to work properly\n- Time synchronization using internal RTC (ESP32), mobile app time or NTP\n- Integrated actions scheduler supporting *extended cron expressions* and JavaScript\n- Device discovery via SSDP/UPnP with customizable device name\n- Multi-channel I/O: HTTP, WebSocket, SSE, MQTT, Serial\n- Builtin status LED logic\n- Builtin Wi-Fi Configuration/Pairing button\n- Builtin GPIO control API\n- Multi-threading support, event router, extensible API\n- Can connect directly to *HomeGenie Panel* either via Wi-Fi access point or hotspot/tethering\n- Can be easily connected to *HomeGenie Server* and other services via MQTT\n- Works also without Internet connection\n\n## Applications\n\n- Wearable devices\n- Smart Homes\n- Building Automation\n- Robotics\n- Remote controls\n- Health monitoring\n- Education\n\n\n## Building and flashing the firmware\n\nThe firmware can be installed using [Platform.IO core](https://docs.platformio.org/en/latest/installation.html) CLI.\nAfter installing *Platform.IO core*, download [HomeGenie Mini](https://github.com/genielabs/homegenie-mini/releases) source code,\nunzip it and open a terminal with the current directory set to `homegenie-mini` folder.  \nThen enter the following commands to install libraries required to build the firmware:\n\n```bash\npio update\npio lib install\n```\n\nTo actually build and install *HomeGenie Mini* firmware, connect your ESP device to your\nPC's USB port and issue the command:\n\n```bash\npio run -e default -t upload\n```\n\n**Congratulations!! =)** You've just got a new shiny HomeGenie Mini device up and running.\n\n\n## Configuration environments\n\nThe option `-e default` shown in the previous command is used to specify the configuration environment.\nThe **default** environment is for building the base firmware for a generic *ESP32* board.\n\nTo list all available configurations enter the following command:\n\n```bash\npio project config\n```\n\nBy editing the `platformio.ini` file is possible to add custom configurations to build your own version\nof the firmware to support different hardware and functionality.\n\n\n## Connecting the device\n\nOnce the firmware is installed you can configure and control the device using\nthe [HomeGenie Panel](https://play.google.com/store/apps/details?id=com.glabs.homegenieplus) app available on Google Play.\n\nThe status LED of the device will blink continuously indicating that it is not\nconnected to Wi-Fi.  \nThe device can be configured and connected to Wi-Fi very easily by enabling\nWPS on your router and by pressing the WPS button on the device for at least 5\nseconds. The status LED will stop blinking and stay on while the WPS mode is\nactive on the device.\n\nAfter pairing, the device will start blinking quickly again for about 5 seconds, and then\nit will blink slowly indicating that is connected correctly to Wi-Fi. It will then appear\nin the list of detected devices in the connections discovery page of *HomeGenie Panel*.\n\n![HomeGenie Panel - Discovery: select device](data/images/phone/hg_panel_discovery_select.png)\n\nSelect it from the list and click the *\"Done\"* button.\n\nIf WPS is not available on your router, you can alternatively set up your device\nvia Bluetooth if it is enabled on your phone when you start the connection discovery\nprocess on the *HomeGenie Panel*.\n\nThe new HG-Mini device will be detected via Bluetooth and the app will display a\ndialog to configure the device name and data to connect it to Wi-Fi.\nAfter confirming the settings, the HG-Mini device will exit pairing mode, reset\nand connect to Wi-Fi.\n\nDepending on the installed firmware version you will be able to select different kind of modules\nto show in the panel dashboard. The following picture refers to the `smart-sensor-d1-mini-esp32`\nfirmware that implements temperature and light sensor and 4 GPIO switches.\n\n![HomeGenie Panel - Dashboard](data/images/phone/hg_panel_dashboard.png)\n\n\n### Connecting to HomeGenie Server\n\nHG-Mini devices can also be connected to [HomeGenie Server](https://github.com/genielabs/HomeGenie)\nconfiguring the *MQTT client* as shown in the following picture.\n\n![HomeGenie Server - MQTT configuration](data/images/phone/hg_server_mqtt_config.png)\n \nIs then possible to use HG-mini device for automation tasks, logging, statistics and use of all other\nfeatures available in *HomeGenie Server*.\n\n![HomeGenie Server - Dashboard](data/images/phone/hg_server_dashboard.png)\n\n\n\n\n## Monitoring via serial port\n\nWhen the device is connected to your PC's USB port, you can monitor its activity logs\nby entering the following command::\n\n```bash\npio device monitor -b 115200\n```\n\n**Example output**\n```\n[1970-01-01T00:00:00.055Z] HomeGenie Mini 1.2.0\n[1970-01-01T00:00:00.056Z] Booting...\n[1970-01-01T00:00:00.057Z] + Starting HomeGenie service\n[1970-01-01T00:00:00.068Z] + Starting NetManager\n[1970-01-01T00:00:00.068Z] |  - Connecting to WI-FI .\n[1970-01-01T00:00:00.187Z] |  - WI-FI SSID: HG-NET\n[1970-01-01T00:00:00.188Z] |  - WI-FI Password: *\n[1970-01-01T00:00:00.214Z] |  x WiFi disconnected\n[1970-01-01T00:00:00.774Z] |  ✔ HTTP service\n[1970-01-01T00:00:00.784Z] |  ✔ WebSocket server\n[1970-01-01T00:00:00.786Z] |  ✔ MQTT service\n[1970-01-01T00:00:00.791Z] @IO::GPIO::GPIOPort [Status.Level 0]\n[1970-01-01T00:00:00.792Z] :Service::HomeGenie [IOManager::IOEvent] \u003e\u003e [domain 'HomeAutomation.HomeGenie' address '14' event 'Status.Level']\n[1970-01-01T00:00:00.807Z] @IO::GPIO::GPIOPort [Status.Level 0]\n[1970-01-01T00:00:00.809Z] :Service::HomeGenie [IOManager::IOEvent] \u003e\u003e [domain 'HomeAutomation.HomeGenie' address '27' event 'Status.Level']\n[1970-01-01T00:00:00.822Z] READY.\n[1970-01-01T00:00:00.823Z] @IO::Sys::Diagnostics [System.BytesFree 147128]\n[1970-01-01T00:00:00.835Z] :Service::HomeGenie [IOManager::IOEvent] \u003e\u003e [domain 'HomeAutomation.HomeGenie' address 'mini' event 'System.BytesFree']\n[1970-01-01T00:00:00.848Z] :Service::EventRouter dequeued event \u003e\u003e [domain 'HomeAutomation.HomeGenie' address 'mini' event 'System.BytesFree']\n[2023-12-29T17:01:11.050Z] |  - RTC updated via TimeClient (NTP)\n[2023-12-29T17:01:11.053Z] |  ✔ UPnP friendly name: Bagno\n[2023-12-29T17:01:11.054Z] |  ✔ SSDP service\n[2023-12-29T17:01:11.200Z] |  - Connected to 'HG-NET'\n[2023-12-29T17:01:11.201Z] |  - IP: 192.168.x.y\n[2023-12-29T17:01:15.048Z] @IO::Sys::Diagnostics [System.BytesFree 143268]\n[2023-12-29T17:01:15.049Z] :Service::HomeGenie [IOManager::IOEvent] \u003e\u003e [domain 'HomeAutomation.HomeGenie' address 'mini' event 'System.BytesFree']\n[2023-12-29T17:01:15.063Z] :Service::EventRouter dequeued event \u003e\u003e [domain 'HomeAutomation.HomeGenie' address 'mini' event 'System.BytesFree']\n```\n\n\n### Firmware configuration commands\n\nHomeGenie Mini device support also commands via serial terminal. You can enter any API\ncommand using the `/api/` prefix, or enter system commands prefixed by `#` character.\n\n#### System core commands\n\n```\n#CONFIG:device-name \u003cname\u003e\n#CONFIG:wifi-ssid \u003cssid\u003e\n#CONFIG:wifi-password \u003cpasswd\u003e\n#CONFIG:system-time \u003chh\u003e:\u003cmm\u003e:\u003css\u003e.\u003cms\u003e\n#CONFIG:system-zone-id \u003czone_id\u003e\n#CONFIG:system-zone-offset \u003ctz_offset\u003e\n#VERSION\n#RESET\n```\n\n#### Getting/Setting parameters\n\n```\n#GET:\u003ckey\u003e\n#SET:\u003ckey\u003e \u003cvalue\u003e\n```\n\n##### System configuration parameters list \n\n| Key        | Description                | Default          |\n|------------|----------------------------|------------------|\n| `sys-rb-n` | Factory reset button GPIO# | -1 (-1=not used) |\n| `sys-sl-n` | System status LED GPIO#    | -1 (-1=not used) |\n| `io-typ01` | I/O Ch.1 type              |                  |\n| `io-pin01` | I/O Ch.1 GPIO#             | -1 (-1=not used) |\n| `io-typ02` | I/O Ch.2 type              |                  |\n| `io-pin02` | I/O Ch.2 GPIO#             | -1 (-1=not used) |\n| `io-typ03` | I/O Ch.3 type              |                  |\n| `io-pin03` | I/O Ch.3 GPIO#             | -1 (-1=not used) |\n| `io-typ04` | I/O Ch.4 type              |                  |\n| `io-pin04` | I/O Ch.4 GPIO#             | -1 (-1=not used) |\n| `io-typ05` | I/O Ch.5 type              |                  |\n| `io-pin05` | I/O Ch.5 GPIO#             | -1 (-1=not used) |\n| `io-typ06` | I/O Ch.6 type              |                  |\n| `io-pin06` | I/O Ch.6 GPIO#             | -1 (-1=not used) |\n| `io-typ07` | I/O Ch.7 type              |                  |\n| `io-pin07` | I/O Ch.7 GPIO#             | -1 (-1=not used) |\n| `io-typ08` | I/O Ch.8 type              |                  |\n| `io-pin08` | I/O Ch.8 GPIO#             | -1 (-1=not used) |\n\n*Example **setting** configuration from a terminal connected to the serial port of the device:*\n\n```\n#SET:sys-sl-n=10\n#SET:sys-rb-n=0\n#RESET\n```\n\n*Example **getting** configuration value:*\n\n```\n#GET:sys-sl-n\n```\nresponse:\n```\n#GET:sys-sl-n=10\n```\n\n\n## Firmwares examples with source code \n\nIn the examples folder you can find some smart device projects using *HomeGenie Mini* library.\n\nYou can use the following command to list all possible configurations to build the examples:\n\n```shell\npio project config\n```\n\nSee also [HomeGenie Mini Documentation](https://homegenie.it/mini/) for further information\nabout included examples.\n\n\n\n---\n\n# Disclaimer\n\n\u003csmall\u003e\u003ccode\u003e\nTHIS PROJECT IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS PROJECT, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\u003c/code\u003e\u003c/small\u003e\n\n---\n\n\n\n# Previous release (2019)\n\n## HomeGenie Mini v1.1 (playground board)\n\n[![HomeGenie Mini Quick Setup Video](https://raw.githubusercontent.com/genielabs/homegenie-mini/master/pcb/images/video_cover.jpg)](https://youtu.be/CovB1jl3980)\n\n\u003csmall\u003e(click the picture above to watch the video)\u003c/small\u003e\n\n**Hardware features**\n\n- WPS button for quick Wi-Fi protected setup\n- Temperature and light sensors\n- RF transceiver (315/330/433Mhz)\n- Expansion connector (P1) with 4 GPIO configurable as SPI/DIO/PWM\n\n*Example applications of the P1 connector:*\n\n- control up to 4 relays to actuate lights and appliances (DIO)\n- hosting additional sensors, connecting a display or other hardware (SPI)\n- control the brightness of a LED or drive a motor at different speed (PWM)\n- breadboard playground\n\n**Firmware features**\n\n- Automatic discovery (SSDP) for instant client setup\n- GPIO mapping to virtual modules: switch for digital output, dimmer for analog output or sensor for inputs (work in progress)\n- X10 home automation RF protocol encoding and decoding with mapping to virtual modules\n- Modules state persistence\n- HTTP API (subset of standard HomeGenie API)\n- Real time event stream over WebSocket or SSE connection\n- MQTT broker over websocket\n- NTP client for time sync\n- Scripting engine (work in progress)\n- Serial CLI with same API as HTTP\n\n## Assembling a HomeGenie Mini device\n\n![HomeGenie Mini PCB front and rear](https://raw.githubusercontent.com/genielabs/homegenie-mini/master/pcb/images/hg_mini_board_front_rear.png)\n\n\u003csmall\u003e*HomeGenie Mini board front and rear view*\u003c/small\u003e\n\n### STEP 1: Start by soldering the 3 resistors, 2 LEDs, light sensor, temperature sensor and the momentary switch button\n\n![HomeGenie Mini assembling step 1](https://raw.githubusercontent.com/genielabs/homegenie-mini/master/pcb/images/hg_mini_assembling_step_1.png)\n\n### STEP 2: Solder the header pins to the D1 Mini\n\n![HomeGenie Mini assembling step 2](https://raw.githubusercontent.com/genielabs/homegenie-mini/master/pcb/images/hg_mini_assembling_step_2.png)\n\n### STEP 3: Solder the D1 Mini to HomeGenie Mini board\n\n![HomeGenie Mini assembling step 3](https://raw.githubusercontent.com/genielabs/homegenie-mini/master/pcb/images/hg_mini_assembling_step_3.png)\n\n### STEP 4: Optionally solder the RF receiver and transmitter: the firmware currently only support X10 home automation protocol. More protocols might be added in the future (any request?).\n\nThe picture below shows a basic HomeGenie Mini device **without** the RF transceiver but adding the RF transceiver is easy as solder [two more components](https://www.google.it/search?q=rf+MX-FS-03V+MX-05V+315+433+transmitter-receiver+module).\nYou can also take advantage of the expansion port (P1) to connect a [relay module](https://www.google.it/search?q=buy+4+or+2+channels+relay+module+arduino) to control lights and appliances or\nany other additional sensors/components required for your projects.\n\n![HomeGenie Mini assembling step 4](https://raw.githubusercontent.com/genielabs/homegenie-mini/master/pcb/images/hg_mini_assembling_step_4.png)\n\n\n## Components listing\n\nGerber files required for printing the circuit board are located in the `./pcb` folder.\n\n- https://github.com/genielabs/homegenie-mini/tree/master/pcb\n\nYou can use the Gerber file and autonomously get HomeGenie Mini board manufactured from any PCB\nprint service.\n\nIf just need a few boards you can get 3 boards for less than $20 from [AISLER](https://aisler.net/).\nOpen **AISLER** website and click **Get Started** then you will be able to upload\n[HomeGenie Mini Gerber](https://github.com/genielabs/homegenie-mini/raw/master/pcb/HomeGenie_Mini_Gerber_V1.1.25.zip) file and order your PCBs.\n\nThe PCB size is 44mm*50mm.\n\n**Components listing**\n\n- 1 ESP8266 WeMoo D1 mini Wi-Fi module (or equivalent)\n- 1 DS18B20 (temperature sensor)\n- 1 LDR (light sensor)\n- 1 FS1000A (RF transmitter)\n- 1 XY-MK-5V (RF receiver)\n- 1 R1 10kΩ\n- 1 R2 4.7kΩ\n- 1 R3 330Ω\n- 1 R4 330Ω\n- 2 LED 3mm\n- 1 Push button 6mm*6mm\n\n**Source code**\n\n- https://github.com/genielabs/homegenie-mini/tree/master/src\n\n**Release**\n\n- https://github.com/genielabs/homegenie-mini/releases/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgenielabs%2Fhomegenie-mini","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgenielabs%2Fhomegenie-mini","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgenielabs%2Fhomegenie-mini/lists"}