Basestation Setup
On this page
We aim to make the setup process for the base station as simple as possible, however, at the moment, assembling and setting it up requires some basic software and hardware knowledge. We aim to improve this in the future.
Hardware
The currently recommended hardware for a Base Station is the following:
- A ESP32-C3
- A UBlox M8N Module or newer
- There are many counterfeit M8N modules which do not contain the flash memory needed for a required firmware update; confirm before building the Base Station that your module has a flash memory module, and that the firmware version is up to date!
- We generally recommend using a M10N module.
Assembly
Assembling the Base Station can be done either with a breadboard or a normal prototyping board; we do not yet have a finished PCB design. The following pinout is configured by default in the firmware:
- UBlox RX (on M10N boards, sometimes labeled R1) to ESP pin 4
- UBlox TX (on M10N boards, sometimes labeled T1) to ESP pin 3
Software
The Base Station Firmware is compiled using the ESP-IDF. There are two runtime modes:
- "Runtime" mode, which uses the WiFi settings from the NVS and permits provisioning, and
- "Fixed" mode, which uses hard-coded WiFi settings and does not permit runtime provisioning.
For most users, we recommend the "Runtime" mode, which is what the CI builds. For the "Fixed" mode, the following configuration options need to be set:
| Config Option | Description |
|---|---|
| WIFI_STA | The name of the Wi‑Fi station to connect to. |
| WIFI_SECRET | The Wi‑Fi secret / password to use. |
| OPENAGPS_SERVER | The OpenAGPS host server to connect to. (For the project‑hosted instance, this is api.openagps.net.) |
| OPENAGPS_TOKEN | The token used to authenticate the connection to the host server. |
Flashing
If you do not wish to compile the firmware yourself, you can download the firmware artifacts from the latest CI build. Look at the CI build artifacts for the latest build, and download the artifacts zip file.
You'll also need the esptool utility. Either install it from your distros package manager, if available, or install it using pip:
sh pip install esptool
You can then flash the firmware using a command similar to this, from the extracted artifacts directory:
sh cd build/ci python3 -m esptool --chip esp32c3 --port /dev/ttyACM0 write_flash @flash_args
Replace [/dev/ttyACM0]{.title-ref} with the serial port your ESP32-C3 is connected to. The [@flash_args]{.title-ref} file contains the arguments for flashing the firmware, and is included in the artifacts zip file.
Provisioning
See the provisioning documentation for more information on how to provision the Base Station. In short, you need to run the provisioning script on a suitable Linux machine, and use it to connect to the Base Station's WiFi setup AP:
sh python3 -m venv .venv .venv/bin/pip install -r tools/requirements-provision.txt .venv/bin/python tools/provision.py --list # Verify the Base Station can be seen on the network .venv/bin/python tools/provision.py --ssid 'Your Wi-Fi' --server 'https://your-server.example'
The script should also ask for a token; provide it one when asked, this is used to authenticate the Base Station to the OpenAGPS server.
If you need to reset the station to reprovision it, you can either:
- Reflash the whole firmware image as above (which should wipe the NVS), or
- wipe the NVS manually (assuming you used the CI image), by running the following command: [python -m esptool --chip esp32c3 --port /dev/ttyACM{number} erase_region 0x9000 0x6000]{.title-ref}, or
- put the station in a place where it cannot connect to the WiFi network for 60 seconds and wait for it to start the provisioning AP again.