Prerequisites¶

This demo is written against Ubuntu 24.04 LTS.

What you need on the desk¶

Item	Notes
PC	USB host port that does data
ESP32 DevKit-class	Classic ESP32, CH340 UART (often `/dev/ttyUSB0`)
ATGM336H module	GPS+BDS, UART; antenna for later phases
ST7789 240×240	8-pin SPI header on
Solderless breadboard	Half-size (400) or full (830) — enough for a 3V3/GND star
DuPont jumpers	M–M (and M–F if modules need them)
USB data cable	Charge-only cables never enumerate

How the holes are already tied together (before any project wires): Hardware — Breadboard. Parts and silk: Hardware.

1. Base packages¶

sudo apt-get update
sudo apt-get install -y git curl python3

…
Setting up python3 …
Setting up curl …

Check:

git --version
python3 --version
curl --version | head -1

git version 2.x.x
Python 3.12.x
curl 8.x.x …

2. Clone this repo¶

git clone https://github.com/jajera/esp32-gnss-field.git
cd esp32-gnss-field

Cloning into 'esp32-gnss-field'...
…

(Use your fork URL if that’s what you’re working from.)

3. Install PlatformIO Core¶

Official installer into ~/.platformio/penv (no sudo):

curl -fsSL https://raw.githubusercontent.com/platformio/platformio-core-installer/master/get-platformio.py -o /tmp/get-platformio.py
python3 /tmp/get-platformio.py

…
PlatformIO Core has been successfully installed into ~/.platformio/penv

Put pio / esptool on your PATH for this shell (and add the same line to ~/.bashrc if you want it permanent):

export PATH="$PATH:$HOME/.platformio/penv/bin"
pio --version
esptool version

PlatformIO Core, version 6.1.19
esptool v5.3.0

Don’t use sudo pio. First pio run will download the Espressif platform and toolchains — that needs network and can take several minutes.

4. Docs site (authors only — skip for the lab)¶

Only needed if you want to preview or edit this walkthrough. The lab phases don’t require it.

sudo apt-get install -y python3-venv
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

…
Successfully installed zensical-… zensical-patina-…

Serve locally at http://127.0.0.1:8000:

.venv/bin/zensical serve

Serving on http://127.0.0.1:8000

Checkpoint — prerequisites¶

You’re ready for Phase 0 when:

[ ] git, python3, and curl work
[ ] Repo is cloned and you’re in its root
[ ] pio --version and esptool version work without sudo
[ ] Hardware, breadboard, jumpers, antenna, and a data cable are on the desk
[ ] (authors only) .venv/bin/zensical serve comes up

Next: Phase 0 — USB erase (udev + dialout, then plug the board).