Getting Started

This chapter is intended to get you up and running with MeshNOW in no time! We show you how to install MeshNOW and how to use it to create a simple mesh network. Knowledge of Espressif Systems ESP-IDF is a prerequisite to using MeshNOW.

Supported ESP-IDF Versions

MeshNOW targets ESP-IDF v5.0.1 and makes use of the available C++20 features. Newer ESP-IDF versions should be compatible but are not tested. If you’re required to use an older version of ESP-IDF, the following steps will not work for you. However, you can still use MeshNOW by manually copying the files from the Git repository into your project. Be sure to also include the dependencies.

Note

We do not support any other method of installation besides the one listed below, so you’re on your own if you choose to do it manually. Support with any significantly older version is also not guaranteed.

Installing MeshNOW

MeshNOW exposes itself as a single ESP-IDF component that can easily be added to your project! The most convenient way is to use the ESP-IDF Component Manager.

1. Install, enable, and configure the required tooling:

   • ESP-IDF: If you don’t have the correct version installed, follow the ESP-IDF Getting Started Guide.

   • ESP-IDF Component Manager: If you’re using a recent version ESP-IDF, it is enabled by default. Otherwise, follow the their getting started guide.

2. Prepare a project:

   1. Create a new ESP-IDF project as usual or use an existing one.

   2. Open a terminal and navigate to your project directory.

3. Add MeshNOW as a dependency to a component of your choosing, e.g., the main component:

   1. Create the idf_component.yml manifest file in the component’s directory if you haven’t already. You can do so by running idf.py create-manifest --component=<my_component> where <my_component> is the name of your component, e.g., main.

   2. Add a new dependencies entry named meshnow to the manifest file and set its git url field to https://github.com/derkalaender/MeshNOW.git

   Note

   Your idf_component.yml manifest should look something like this:

   dependencies:
     idf:
       version: ">=5.0.1"
     meshnow:
       git: "https://github.com/derkalaender/MeshNOW.git"
   

4. Run idf.py reconfigure to reconfigure the project and let the component manager discover and download MeshNOW and its dependencies.

5. Add meshnow to your PRIV_REQUIRES (or REQUIRES if you’re exposing MeshNOW in your public include files) in the component’s CMakeLists.txt file.

6. MeshNOW needs a few configuration options to be enabled by the user. You can do this by invoking idf.py menuconfig and enabling the following options:

   • Component config -> LWIP -> Enable copy between Layer2 and Layer packets

   • Component config -> LWIP -> Enable IP forwarding

   • Component config -> LWIP -> Enable NAT (new/experimental)

   Alternatively, you can also add the options to your sdkconfig file in the project’s root directory directly:

   CONFIG_LWIP_L2_TO_L3_COPY=y
   CONFIG_LWIP_IP_FORWARD=y
   CONFIG_LWIP_NAT=y
   

Done! You can now use MeshNOW in your project.

What’s Next?

Explore the rest of the documentation!

See the Example Code for some inspiration on how to use MeshNOW.

You can also directly check out the API Reference. It should feel familiar if you’ve used the ESP-IDF and its networking capabilities before.

The SDKConfig Options page lists all the configuration options that MeshNOW exposes for maximum fine-tuning.