{"id":15361557,"url":"https://github.com/princeofpuppers/smart-home-server","last_synced_at":"2026-01-05T02:04:37.458Z","repository":{"id":64943973,"uuid":"567651911","full_name":"PrinceOfPuppers/smart-home-server","owner":"PrinceOfPuppers","description":"A Full Smart Home System and Associated IOT Devices","archived":false,"fork":false,"pushed_at":"2024-05-22T17:34:25.000Z","size":72250,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-05-22T18:44:49.809Z","etag":null,"topics":["embedded","fullstack","iot","smarthome"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PrinceOfPuppers.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2022-11-18T09:03:43.000Z","updated_at":"2024-05-28T05:27:28.414Z","dependencies_parsed_at":"2024-05-28T05:37:45.732Z","dependency_job_id":null,"html_url":"https://github.com/PrinceOfPuppers/smart-home-server","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PrinceOfPuppers%2Fsmart-home-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PrinceOfPuppers%2Fsmart-home-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PrinceOfPuppers%2Fsmart-home-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PrinceOfPuppers%2Fsmart-home-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PrinceOfPuppers","download_url":"https://codeload.github.com/PrinceOfPuppers/smart-home-server/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244894322,"owners_count":20527677,"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":["embedded","fullstack","iot","smarthome"],"created_at":"2024-10-01T12:55:38.287Z","updated_at":"2026-01-05T02:04:37.451Z","avatar_url":"https://github.com/PrinceOfPuppers.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Smart Home Server\n\u003e A Full Smart Home System and Associated IOT Devices\n\n- [DEVICES](#devices)\n- [INSTALLATION](#installation)\n  * [INSTRUCTIONS](#instructions)\n- [ABOUT](#about)\n  * [JOBS AND MACROS](#jobs-and-macros)\n  * [DATASOURCES](#datasources)\n- [PAGES](#pages)\n  * [DASHBOARD](#dashboard)\n  * [NOTE](#note)\n  * [LCD](#lcd)\n  * [REMOTE](#remote)\n  * [SCHEDULE](#schedule)\n  * [TRIGGER](#trigger)\n  * [MACRO](#macro)\n  * [GRAPH](#graph)\n\n# DEVICES\nEach device has its own `README`. Click the links to read more.\n\n[ESP32 Air Quality Station](devices/esp32-air-quality-station/README.md) and [ESP Dashboard](devices/esp-dashboard/README.md):\n\n\u003cimg align=\"left\" height=\"200\" src=\"devices/esp32-air-quality-station/images/full-right.jpg\"\u003e\n\u003cimg align=\"left\" height=\"200\" src=\"devices/esp-dashboard/images/full-right.jpg\"\u003e\n\u003cbr clear=\"left\"/\u003e\n\u003cbr clear=\"left\"/\u003e\n\n[Main Case](devices/main-case/README.md) and [Arduino Blinds Controller](devices/arduino-blinds/README.md):\n\n\u003cimg align=\"left\" height=\"200\" src=\"devices/atmega16u2-monitor/images/full.jpg\"\u003e\n\u003cimg align=\"left\" height=\"200\" src=\"devices/arduino-blinds/images/mechanical.jpg\"\u003e\n\u003cbr clear=\"left\"/\u003e\n\u003cbr clear=\"left\"/\u003e\n\n[Atmega16u2 Monitor](devices/atmega16u2-monitor/README.md)\n\n\u003cimg align=\"left\" height=\"200\" src=\"devices/atmega16u2-monitor/images/full-focused.jpg\"\u003e\n\u003cimg align=\"left\" height=\"200\" src=\"devices/atmega16u2-monitor/images/board.jpg\"\u003e\n\u003cbr clear=\"left\"/\u003e\n\u003cbr clear=\"left\"/\u003e\n\n[ESP Weather Station](devices/esp-weather-station/README.md) and [Arduino Modular Controller](devices/arduino-modular-controller/README.md):\n\n\u003cimg align=\"left\" height=\"200\" src=\"devices/esp-weather-station/images/full.jpg\"\u003e\n\u003cimg align=\"left\" height=\"200\" src=\"devices/arduino-modular-controller/images/motion_dev_pic.jpg\"\u003e\n\u003cbr clear=\"left\"/\u003e\n\u003cbr clear=\"left\"/\u003e\n\n# INSTALLATION\nThis section covers the installation of the central smart-home-server (hereto called \"the server\"). For a full parts list and physical assembly see: [Main Case Readme.md](devices/main-case/README.md)\n\nThe server runs RaspberryPi OS Lite, it has only been tested on a RaspberryPi 4B. I'd recommend using rpi-imager for creating the image as it lets you setup WiFi, SSH, etc, for an easier experience.\n\n### Instructions\n1) Flash an SD card with RaspberryPi OS Lite using rpi-imager, edit the settings to configure your user, WiFi, ssh, and other settings\n\n2) Boot up the server and let it connect to wifi, in your router set a static IP address for the server\n\n3) Reboot the server and connect to it over ssh\n\n4) Ensure a USB stick is connected to the Pi and run: \n\n```\nsudo apt install -y git \u0026\u0026 git clone https://github.com/PrinceOfPuppers/smart-home-server.git \u0026\u0026 cd smart-home-server \u0026\u0026 ./install.sh\n```\n\n5) The Installer will prompt you to select the usb stick from a list (will likley be the only one), after it is finished the server will be ready to go and accessable at its static ip address.\n\nNote: The installer script enables read only file system, this makes the SD card readonly but still allows writing to the USB stick. You can disable this and re-enable it using `sudo raspi-config`\n\n# ABOUT\nThe smart-home-server (hereto called \"the server\") is a device for collecting data and controlling IOT devices (hereto called \"devices\"). The server runs a full web interface for easy control on mobile or desktop.\n\nThe server's functionality is best understood through two categories, [Jobs and Macros](#jobs-and-macros) and [Datasources](#datasources).\n\n## Jobs and Macros\nJobs are things the server can do, they include:\n- Transmitting RF signals (for controlling RF outlets and relays)\n- Sending HTTP requests\n- Updating remote LCD Dashboard formats (see LCDs page)\n- Running Job Macros\n- Updating the server\n- And more\n\nJobs can be organized into macros and setup to trigger in on RF signals, button presses on the server's case, or manually through the web page.\n\nJobs and macros can also be run using a scheduler (i.e. turn off the lights at 11pm) or can be triggered on conditions (i.e. turn on the humidifier whenever relative humidity is below 35%). See the [Schedule](#schedule) and [Trigger](#trigger) pages for more details.\n\nMacros can also include delays and other macros.\n\n### Example\nHere is an example of a simple nighttime macro:\n\n\u003cimg align=\"left\" height=\"500\" src=\"images/macro-example.png\"\u003e\n\u003cbr clear=\"left\"/\u003e\n\u003cbr clear=\"left\"/\u003e\n\nThis macro turns off all the lights, turns off a loud air filter in the bedroom, waits for 8h30min, prevents you from oversleeping by turning on the bedroom light, and then turns everything in the bedroom off after 30 more minutes.\n\nThis macro could be hooked up to an RF button outside the bedroom to be run without having to open the web app (how I do it).\n\nThe macros like bedroom on/off would be replaced with single RF switching jobs, i.e.) `press bedroom ch: 1 on`, for the example macros where used so they could be labeled.\n\n## Datasources\nThe server collects data from `datasources` with a set polling period. The data can then be used to:\n- [Trigger](#trigger) server [Jobs](#jobs-and-macros) on conditions\n- Displayed on the [Dashboard](#dashboard)\n- Create [Graphs](#graph)\n- Displayed on local and remote [LCDs](#lcd)\n\nExamples of each Application:\n\n\u003cimg align=\"left\" height=\"200\" src=\"images/dashboard-example.png\"\u003e\n\u003cimg align=\"left\" height=\"200\" src=\"images/graph-example.jpg\"\u003e\n\u003cimg align=\"left\" height=\"200\" src=\"devices/esp-dashboard/images/full-front.jpg\"\u003e\n\u003cbr clear=\"left\"/\u003e\n\u003cbr clear=\"left\"/\u003e\n\n\u003cimg align=\"left\" height=\"150\" src=\"images/trigger-example.png\"\u003e\n\u003cbr clear=\"left\"/\u003e\n\u003cbr clear=\"left\"/\u003e\n\nDatasources can be added and changed on the `Datasources` tab if they fit into one of the existing types:\n- `Forex`: currency converstion\n- `Clock`: tells time\n- `AQ`: air quality, temprature and humidity station\n- `TempHumid`: temprature and humidity station\n- `WeatherImage`: current weather with ascii art image\n- `WeatherCurrent`: current weather simple representation\n- `Forcast`: long term forcast chart\n- `Errors`: log of errors in the smart home\n- `JobLog`: log of run jobs\n- `RfLog`: log of rf rx/tx\n- `Version`: smart home version\n\n\nNew Datasource Form (left). Edit existing Datasource Form (right):\n\n\u003cimg align=\"left\" height=\"200\" src=\"images/new-datasource.png\"\u003e\n\u003cimg align=\"left\" height=\"200\" src=\"images/datasource.png\"\u003e\n\u003cbr clear=\"left\"/\u003e\n\u003cbr clear=\"left\"/\u003e\n\nEach Datasource can be displayed in the Dashboard and provides values that can be consumed by Job Triggers, Graphs and LCDs\n\nNew types of Datasources can be added [here](smart_home_server/data_sources/datasourceTypes.py), by:\n1) Creating a new subclass of `Datasource` (use an existing one as a base), Any required arguments should be annotated so they appear correctly in the `Datasource` form\n2) Adding a `local` function which returns `{ 'str': '...', 'data':{...} }` where `str` is shown in dashboard and `data` contains the values used by triggers, graphs and etc (this function is polled to get the data).\n3) Adding a `values` property which specifies what fields in `data` are relevant and what they should be called\n4) Set a sane default polling period, although this is editable in the datasource form\n\n# Pages\n\n## Dashboard\nA page for displaying desired datasources in an easy to read way, clicking on the name tag will refresh its information. Each datasource can be customized with buttons to hide its contents, colored name tags, buttons to make HTTP requests, and more.\n\n\u003cimg align=\"left\" height=\"300\" src=\"images/pages/dashboard.jpg\"\u003e\n\u003cbr clear=\"left\"/\u003e\n\u003cbr clear=\"left\"/\u003e\n\n## Note\nA page to create, display and edit notes.\n\n\u003cimg align=\"left\" height=\"300\" src=\"images/pages/note.jpg\"\u003e\n\u003cbr clear=\"left\"/\u003e\n\u003cbr clear=\"left\"/\u003e\n\n## LCD\nA page to add and update local and [remote LCD](devices/esp-dashboard/README.md) dashboards.\n\nLCDs display formatted text containing datasources, i.e. `{clock} 123` will be replaced with `02:03 PM 123` and will be updated every minute when the `{clock}` changes. This format is set on the LCD page, a list of all formats is provided under `Cheat Sheet`. Numbers can be rounded like so: `{temp:.0f}` for 0 decimal places or `{temp:.1f}` for 1 decimal place.\n\nEach LCD has its own number (0 for local and 1 or more for remote), upon power up the LCDs will reach out to the server to connect, after which the server will send updates whenever the text changes.\n\n\u003cimg align=\"left\" height=\"300\" src=\"images/pages/lcd.jpg\"\u003e\n\u003cbr clear=\"left\"/\u003e\n\u003cbr clear=\"left\"/\u003e\n\n## Remote\nA page for using, adding and editing RF remotes. The server contains an RF receiver to copy existing remotes which can then hook into the server's [job system](#jobs-and-macros), in addition to directly using the copied remote from this page.\n\nEach remote can be named, and additional buttons can be added using the forms at the bottom of the page.\n\n\u003cimg align=\"left\" height=\"300\" src=\"images/pages/remote-top.jpg\"\u003e\n\u003cimg align=\"left\" height=\"300\" src=\"images/pages/remote-bottom.jpg\"\u003e\n\u003cbr clear=\"left\"/\u003e\n\u003cbr clear=\"left\"/\u003e\n\n## Schedule\nA page for triggering [jobs and macros](#jobs-and-macros) repeatedly on a schedule. The server can be setup to run a job on an interval or at a specific time every day or week, for example turn on the Christmas lights at 5pm every day and turn them off at 5am every day.\n\n\u003cimg align=\"left\" height=\"300\" src=\"images/pages/schedule.jpg\"\u003e\n\u003cbr clear=\"left\"/\u003e\n\u003cbr clear=\"left\"/\u003e\n\n## Trigger\nA page for triggering [jobs and macros](#jobs-and-macros) on conditions involving [datasources](#dataSources). The server can be setup to run a job whenever a condition is met, for example whenever humidity is over 30%. comparisons can be made between two datasources as well, for example if you have 2 temperature sensors in different rooms, you can trigger a fan to turn on if room A temp is less than room B temp.\n\nNote the condition is denounced, so it will only trigger once until the condition is no longer met. Using the humidity example, going below 30% will trigger the condition, but it will not trigger again until humidity goes above 30% and then below 30% again. This is to prevent spamming.\n\n\u003cimg align=\"left\" height=\"300\" src=\"images/pages/trigger.jpg\"\u003e\n\u003cbr clear=\"left\"/\u003e\n\u003cbr clear=\"left\"/\u003e\n\n## Macro\nA page for combining [jobs (and macros) into macros](#jobs-and-macros), macros can include jobs, delays and other macros to allow the easy triggering of complex tasks manually, on schedules or using the trigger system. See the [jobs and macro section](#jobs-and-macros) for examples.\n\n\u003cimg align=\"left\" height=\"300\" src=\"images/pages/macro.jpg\"\u003e\n\u003cbr clear=\"left\"/\u003e\n\u003cbr clear=\"left\"/\u003e\n\n## Graph\nA page for creating plots of datasources over time. New graphs can be created by selecting a datasource, a color, and a time interval to plot over. All the plots are created server side and served as an image so they can be easily saved. Clicking on the plots name or refreshing the page will update it.\n\n\u003cimg align=\"left\" height=\"300\" src=\"images/pages/graph.jpg\"\u003e\n\u003cbr clear=\"left\"/\u003e\n\u003cbr clear=\"left\"/\u003e\n\nIf an [Atmega16u2 Monitor](./devices/atmega16u2-monitor/README.md) is connected, you can press the `Monitor` button to push it to the screen where it will be updated whenever new data is added.\n\n\u003cimg align=\"left\" height=\"200\" src=\"devices/atmega16u2-monitor/images/ui-monitor.png\"\u003e\n\u003cimg align=\"left\" height=\"200\" src=\"devices/atmega16u2-monitor/images/full-focused.jpg\"\u003e\n\u003cbr clear=\"left\"/\u003e\n\u003cbr clear=\"left\"/\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprinceofpuppers%2Fsmart-home-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprinceofpuppers%2Fsmart-home-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprinceofpuppers%2Fsmart-home-server/lists"}