HomeNet

Decentralized, secure, in-the-home communication with IoT devices with support for IEEE 802.15.4 based network-communication.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

• About the Project
  • Built With
• Getting Started
  • Prerequisites
  • Installation
• Usage
• Roadmap
• Contributing
• License
• Contact
• Acknowledgements

About The Project

So what is it?

At the core, this is a simple mesh network created with the help of OpenThread, an open source version of the mesh networking system Thread.

Thread 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.

How the devices communicate

Here is a somewhat simplified example of how it might look:

Device 1 <-> Device 2
  ^            ^
  |            |
  v            |
  Device 3 <----

In 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.

For example our network might reconfigure to look something like this:

Device 1 <-> Device 2

Why a mesh network?

We 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.

Meshes 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.

How is communication done?

In this secure mesh, we allow our devices to communicate with one another directly over IPv6, 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(the one that you're used to using) can only really hold up to a couple billions.

Speaking of communication, the real protocols behind the 'texting' here in this mesh isn't anything new, rather it takes advantage of 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.

A UDP 'connection' may look like this:

          (request)
1. Sender <-------- Receiver
          (response)
2. Sender --------> Receiver
          (response)
3. Sender --------> Receiver
          (response)
4. Sender --------> Receiver

So 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.

What makes this decentralized?

According to the Merriam-Webster Dictionary, decentralized means:

1: the dispersion or distribution of functions and powers
> a decentralization of powers

specifically, government: the delegation of power from a central authority to regional and local authorities
> the decentralization of the state's public school system
> government decentralization

2 sociology: the redistribution of population and industry from urban centers to outlying areas

In 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 is open source, and so is this project. You are free to modify it accordingly.

Along with that, this network doesn't rely off of anything like WiFi or Cellular Data which may be controlled by external companies.

These mesh networks in question are also created independantly of one another. If you would like to modify your mesh's settings with ot-cli, you are free to do so as it could make your mesh more independent.

TLDR: HomeNet is a special type of network called a mesh network, with secure messaging using UDP, often used for stuff like online games.

Before you continue any further, please not only consider contributing to this project, but also Hack Club, 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.

Look interesting? Let's go to Prerequisites.

Built With

• esp-idf@v5.3
• M5NanoC6 or any other ESP32 with support for OpenThread

Getting Started

To get a local copy up and running follow these simple steps.

Prerequisites

Supported Hardware

• ESP32C6-*
• ESP32C5-*
• ESP32H2-*

I highly recommend getting an M5NanoC6, ESP32H2-*, 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.

Installation

1. Clone the repo

git clone https://github.com/dj1ch/HomeNet.git

2. Install esp-idf: Follow documentation and install version 5.3, or you can install the VSCode extension.

3. Set board target

idf.py set-target <your_esp32*_board>

If it asks that you delete the build directory or sdkconfig, you will need to do that to compile for that board.

If you're using the VSCode extension you'll need to click Open ESP-IDF Terminal beforehand to create an esp-idf shell.

4. Build the project

idf.py build

5. Flash to your ESP32(replace PORT with the port connected to your ESP32)

idf.py -p PORT flash

or you can run

idf.py flash

If 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.

Usage

Here are the commands that you can use:

• set_nickname Sets the nickname of a peer
• get_nickname Gets the peer's nickname based on their IPv6 address
• get_ipv6 Gets the peer's IPv6 address bassed on nickname
• send_message Sends a message to a peer manually
• configure_network Configures one of your devices as the leader of the mesh network, though this doesn't really change anything about message sending
• configure_joiner Configures any device as a joiner, meaning that it joins the mesh created by the device that ran the configure_network command
• turn_on_led Turns on the onboard LED (must be configured)
• turn_off_led Turns off the onboard LED (must be configured)
• get_lfs_entries Lists all LFS entries
• clear_lfs_entries Clears LFS entries (if any)
• chat_logs Checks chat logs, either all of them or those sent to a specific IPv6 address

You 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.

Roadmap

As of now I would like to implement/am in the progress of implementing:

• Create basic messaging w/ commands
• Create custom method for anyone to advertise their presence to other instances of HomeNet
• Allow the saving of clients like phone contacts
• Allow direct communication with these saved clients like DMs
• Establish a method to ensure the security of the connection
• Chat logs
• Rewrite UDP communication using custom receivers, transmitters, etc
  • Custom transmitter
  • Custom receiver
• Make documentation simpler for other audiences (may need to reach out)
• (Maybe) Make an application that communicates with the ESP over BLE to send messages e.g Meshtastic App(s)

See the open issues for a list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Contact

dj1ch - tg.1ch0712@gmail.com

Personal Website - dj1ch.pages.dev/contact

Project Link: https://github.com/dj1ch/HomeNet

Acknowledgements

• Hack Club
• Meshtastic
• Espressif
• Espressif OpenThread fork
• ESP32 IEEE 802.15.4 Example
• ESP32 Advanced Console example
• ESP32 Basic Console example
• ot-send Example
• ot-receive Example
• Nano Framework Interpreter
• And many more...!

Additional learning

• Thread Primer: What is Thread?
• What is a mesh network?
• An introduction to IEEE STD 802.15.4
• Introduction of IEEE 802.15.4 Technology
• IEEE 802.15.4 Standard: a tutorial / primer
• OpenThread - Espressif Documentation

Made with ❤️ by @dj1ch