{"id":22392191,"url":"https://github.com/dj1ch/homenet","last_synced_at":"2025-10-09T07:08:38.615Z","repository":{"id":264773802,"uuid":"856221787","full_name":"dj1ch/HomeNet","owner":"dj1ch","description":"Decentralized, secure, in-the-home communication with IoT devices. ","archived":false,"fork":false,"pushed_at":"2025-01-19T04:22:10.000Z","size":676,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-19T04:26:44.121Z","etag":null,"topics":["ieee802154","iot-application","openthread","texting"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dj1ch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2024-09-12T07:48:03.000Z","updated_at":"2025-01-19T04:03:56.000Z","dependencies_parsed_at":"2024-11-26T09:27:24.142Z","dependency_job_id":"550b338d-0086-4593-97e1-797942bafafd","html_url":"https://github.com/dj1ch/HomeNet","commit_stats":null,"previous_names":["dj1ch/homenet"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dj1ch%2FHomeNet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dj1ch%2FHomeNet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dj1ch%2FHomeNet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dj1ch%2FHomeNet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dj1ch","download_url":"https://codeload.github.com/dj1ch/HomeNet/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":236615463,"owners_count":19177564,"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":["ieee802154","iot-application","openthread","texting"],"created_at":"2024-12-05T04:15:43.218Z","updated_at":"2025-10-09T07:08:33.580Z","avatar_url":"https://github.com/dj1ch.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"![GitHub contributors](https://img.shields.io/github/contributors/dj1ch/HomeNet)\n![GitHub forks](https://img.shields.io/github/forks/dj1ch/HomeNet)\n![GitHub Repo stars](https://img.shields.io/github/stars/dj1ch/HomeNet)\n![GitHub Repo stars](https://img.shields.io/github/stars/dj1ch/HomeNet)\n![GitHub Issues](https://img.shields.io/github/issues/dj1ch/HomeNet)\n![GitHub License](https://img.shields.io/github/license/dj1ch/HomeNet)\n\n\u003c!-- PROJECT LOGO --\u003e\n\u003cbr /\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/dj1ch/HomeNet\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/dj1ch/HomeNet/refs/heads/main/images/logo.png\" alt=\"Logo\" width=\"400\" height=\"300\"\u003e\n  \u003c/a\u003e\n\n  \u003ch3 align=\"center\"\u003eHomeNet\u003c/h3\u003e\n\n  \u003cp align=\"center\"\u003e\n    Decentralized, secure, in-the-home communication with IoT devices with support for IEEE 802.15.4 based network-communication.\n    \u003cbr /\u003e\n    \u003ca href=\"https://github.com/dj1ch/HomeNet\"\u003e\u003cstrong\u003eExplore the docs »\u003c/strong\u003e\u003c/a\u003e\n    \u003cbr /\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"https://youtu.be/-zFOi41-QDw\"\u003eView Demo\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/dj1ch/HomeNet/issues\"\u003eReport Bug\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/dj1ch/HomeNet/issues\"\u003eRequest Feature\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n\n\n\u003c!-- TABLE OF CONTENTS --\u003e\n## Table of Contents\n\n* [About the Project](#about-the-project)\n  * [Built With](#built-with)\n* [Getting Started](#getting-started)\n  * [Prerequisites](#prerequisites)\n  * [Installation](#installation)\n* [Usage](#usage)\n* [Roadmap](#roadmap)\n* [Contributing](#contributing)\n* [License](#license)\n* [Contact](#contact)\n* [Acknowledgements](#acknowledgements)\n\n\u003c!-- ABOUT THE PROJECT --\u003e\n## About The Project\n\n### So what is it?\n\nAt the core, this is a simple mesh network created with the help of [OpenThread](https://openthread.io/), an open source version of the mesh networking system [Thread](threadgroup.org).\n\nThread is a low-power, low latency mesh network technology designed for Internet of Things (IoT) devices. It enabled devices to communicate **directly** (keep in mind very important) or through multiple paths with each other, forming a resilient network with multiple methods to reach each node.\n\n### How the devices communicate\n\nHere is a somewhat simplified example of how it might look:\n\n```md\nDevice 1 \u003c-\u003e Device 2\n  ^            ^\n  |            |\n  v            |\n  Device 3 \u003c----\n```\n\nIn simpler words, Thread is a resilient network designed to handle potentially harmful changes, reconfiguring and adapting based on the given environment. For example, if a node were to suddenly go down, the network will reconfigure to fix this issue. It is meant for smaller devices such as the ESP32C6, a key SoC in this project.\n\nFor example our network might reconfigure to look something like this:\n\n```md\nDevice 1 \u003c-\u003e Device 2\n```\n\n### Why a mesh network?\n\nWe use this mesh network to ensure that a secure medium is established between devices for the sake of security, a core idea of this project.\n\nMeshes are naturally a lot more secure than regular networks. Their structures, like said before, have no sort of centralization, and can configure at will. There is a lot of redundancy, having the posssibility of multiple routers, commissioners, children, etc. Although this might seem inconvenient, it eliminates the reliance of one device, which could serve as a point of failure. This allows our network to prevail under **most** circumstances.\n\n### How is communication done?\n\nIn this secure mesh, we allow our devices to communicate with one another directly over [IPv6](https://www.cisco.com/c/en/us/solutions/ipv6/overview.html), the latest, though probably not the most convenient networking protocol to use. Addresses tend to be lengthier which allows undecillions(billion billion billions) of devices to have unique devices, while [IPv4](https://bluecatnetworks.com/glossary/what-is-ipv4/)(the one that you're used to using) can only really hold up to a couple billions.\n\nSpeaking of communication, the real protocols behind the 'texting' here in this mesh isn't anything new, rather it takes advantage of [UDP](https://www.cloudflare.com/learning/ddos/glossary/user-datagram-protocol-udp/), a packet often used for data transfer, whether it be videos, DNS lookups, or online gaming (yes, online gaming). Although one could argue that TCP is much more secure, I find UDP much more easier to use with the Openthread API, and more well established.\n\nA UDP 'connection' may look like this:\n\n```md\n          (request)\n1. Sender \u003c-------- Receiver\n          (response)\n2. Sender --------\u003e Receiver\n          (response)\n3. Sender --------\u003e Receiver\n          (response)\n4. Sender --------\u003e Receiver\n```\n\nSo the messages here can only really be seen in the mesh, if they're ever received. Lucky for us, devices in this mesh are programmed to handle the data received, as well as sending it.\n\n### What makes this decentralized?\n\nAccording to the *Merriam-Webster Dictionary*, *decentralized* means:\n\n```md\n\n1: the dispersion or distribution of functions and powers\n\u003e a decentralization of powers\n\nspecifically, government: the delegation of power from a central authority to regional and local authorities\n\u003e the decentralization of the state's public school system\n\u003e government decentralization\n\n2 sociology: the redistribution of population and industry from urban centers to outlying areas\n\n```\n\nIn this context, *decentralized* implies that there is nobody controlling this mesh network but **you**. You have total control over this network, and what you do with it is not logged by me or anyone else. The code for [OpenThread](https://openthread.io/) is open source, and so is this project. You are free to modify it accordingly.\n\nAlong with that, this network doesn't rely off of anything like WiFi or Cellular Data which may be controlled by external companies.\n\nThese mesh networks in question are also created independantly of one another. If you would like to modify your mesh's settings with [ot-cli](https://openthread.io/reference/cli), you are free to do so as it could make your mesh more independent.\n\n\n**TLDR: HomeNet is a special type of network called a mesh network, with secure messaging using UDP, often used for stuff like online games.**\n\n**Before you continue any further, please not only consider contributing to this project, but also [Hack Club](https://hackclub.com/), who supported me throughout development and kept me motivated to continue this project. Their funding allowed me to purchase more hardware without the risk of this being a potential financial burden.**\n\nLook interesting? Let's go to [Prerequisites](#prerequisites).\n\n### Built With\n\n* [esp-idf@v5.3](https://github.com/espressif/esp-idf/tree/v5.3)\n* [M5NanoC6](https://shop.m5stack.com/products/m5stack-nanoc6-dev-kit) or any other ESP32 with support for OpenThread\n\n\u003c!-- GETTING STARTED --\u003e\n## Getting Started\n\nTo get a local copy up and running follow these simple steps.\n\n### Prerequisites\n\n### Supported Hardware\n\n* `ESP32C6-*`\n* `ESP32C5-*`\n* `ESP32H2-*`\n\nI highly recommend getting an [M5NanoC6](https://shop.m5stack.com/products/m5stack-nanoc6-dev-kit), [ESP32H2-*](https://www.amazon.com/Espressif-ESP32-H2-DevKitM-1-N4-Development-Board/dp/B0BWM83LMF), or ESP32C5-* (whenever that comes out) as these are devices not only supported by `esp-idf` but also `Openthread`. You can probably find them cheaper elsewhere but usually I go with well known sellers as they are often much more trustworthy than a random website and/or person.\n\n### Installation\n\n1. Clone the repo\n\n```sh\ngit clone https://github.com/dj1ch/HomeNet.git\n```\n\n2. Install `esp-idf`: Follow [documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/#installation) and install version 5.3, or you can install the [VSCode extension](https://github.com/espressif/vscode-esp-idf-extension).\n\n3. Set board target\n\n```sh\nidf.py set-target \u003cyour_esp32*_board\u003e\n```\n\nIf it asks that you delete the build directory or `sdkconfig`, you will need to do that to compile for that board.\n\nIf you're using the VSCode extension you'll need to click `Open ESP-IDF Terminal` beforehand to create an `esp-idf` shell.\n\n4. Build the project\n\n```sh\nidf.py build\n```\n\n5. Flash to your ESP32(replace `PORT` with the port connected to your ESP32)\n\n```sh\nidf.py -p PORT flash\n```\n\nor you can run\n\n```sh\nidf.py flash\n```\n\nIf you want to make things easier on yourself, you can use the VSCode Extension to select your COM Port with button `Select Port to use`, then click on the fire icon that says `ESP-IDF: Build, Flash, and Monitor`. This will do everything that has been said, assuming that you've set your board with the `Set Espressif Device Target` button.\n\n\u003c!-- USAGE EXAMPLES --\u003e\n## Usage\n\nHere are the commands that you can use:\n\n* `set_nickname` Sets the nickname of a peer\n* `get_nickname` Gets the peer's nickname based on their IPv6 address\n* `get_ipv6` Gets the peer's IPv6 address bassed on nickname\n* `send_message` Sends a message to a peer manually\n* `configure_network` Configures **one** of your devices as the leader of the mesh network, though this doesn't really change anything about message sending\n* `configure_joiner` Configures **any** device as a joiner, meaning that it joins the mesh created by the device that ran the `configure_network` command\n* `turn_on_led` Turns on the onboard LED (must be configured)\n* `turn_off_led` Turns off the onboard LED (must be configured)\n* `get_lfs_entries` Lists all LFS entries\n* `clear_lfs_entries` Clears LFS entries (if any)\n* `chat_logs` Checks chat logs, either all of them or those sent to a specific IPv6 address\n\nYou can simply run the command without any arguments e.g `set_nickname` to see if any are needed. With an exception for the LED commands and some LFS commands there will most likely be an argument required for it to run.\n\n\u003c!-- ROADMAP --\u003e\n## Roadmap\n\nAs of now I would like to implement/am in the progress of implementing:\n\n* [x] Create basic messaging w/ commands\n* [x] Create custom method for anyone to advertise their presence to other instances of HomeNet\n* [x] Allow the saving of clients like phone contacts\n* [x] Allow direct communication with these saved clients like DMs\n* [x] Establish a method to ensure the security of the connection\n* [x] Chat logs\n* [ ] Rewrite UDP communication using custom receivers, transmitters, etc\n  * [x] Custom transmitter\n  * [ ] Custom receiver\n* [x] Make documentation simpler for other audiences (may need to reach out)\n* [ ] (Maybe) Make an application that communicates with the ESP over BLE to send messages e.g [Meshtastic App(s)](https://meshtastic.org/docs/software/)\n\nSee the [open issues](https://github.com/dj1ch/HomeNet/issues) for a list of proposed features (and known issues).\n\n\u003c!-- CONTRIBUTING --\u003e\n## Contributing\n\nContributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are **greatly appreciated**.\n\n1. Fork the Project\n2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the Branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n\u003c!-- LICENSE --\u003e\n## License\n\nDistributed under the MIT License. See `LICENSE` for more information.\n\n\u003c!-- CONTACT --\u003e\n## Contact\n\ndj1ch - [tg.1ch0712@gmail.com](tg.1ch0712@gmail.com)\n\nPersonal Website - [dj1ch.pages.dev/contact](https://dj1ch.pages.dev/contact)\n\nProject Link: [https://github.com/dj1ch/HomeNet](https://github.com/dj1ch/HomeNet)\n\n\u003c!-- ACKNOWLEDGEMENTS --\u003e\n## Acknowledgements\n\n* [Hack Club](https://hackclub.com/)\n* [Meshtastic](https://meshtastic.org/)\n* [Espressif](https://github.com/espressif/)\n* [Espressif OpenThread fork](https://github.com/espressif/openthread)\n* [ESP32 IEEE 802.15.4 Example](https://github.com/espressif/esp-idf/blob/master/examples/ieee802154/ieee802154_cli/main/esp_ieee802154_cli.c)\n* [ESP32 Advanced Console example](https://github.com/espressif/esp-idf/tree/v5.3/examples/system/console/advanced)\n* [ESP32 Basic Console example](https://github.com/espressif/esp-idf/tree/v5.3/examples/system/console/basic)\n* [ot-send Example](https://github.com/UCSC-ThreadAscon/ot-send)\n* [ot-receive Example](https://github.com/UCSC-ThreadAscon/ot-receive)\n* [Nano Framework Interpreter](https://github.com/nanoframework/nf-interpreter)\n* And many more...!\n\n## Additional learning\n\n* [Thread Primer: What is Thread?](https://openthread.io/guides/thread-primer)\n* [What is a mesh network?](https://support.google.com/googlenest/answer/7182746?hl=en)\n* [An introduction to IEEE STD 802.15.4](https://ieeexplore.ieee.org/document/1655947)\n* [Introduction of IEEE 802.15.4 Technology](https://www.geeksforgeeks.org/introduction-of-ieee-802-15-4-technology/)\n* [IEEE 802.15.4 Standard: a tutorial / primer](https://www.electronics-notes.com/articles/connectivity/ieee-802-15-4-wireless/basics-tutorial-primer.php)\n* [OpenThread - Espressif Documentation](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-guides/openthread.html)\n\nMade with :heart: by [@dj1ch](https://github.com/dj1ch)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdj1ch%2Fhomenet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdj1ch%2Fhomenet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdj1ch%2Fhomenet/lists"}