Skip to content

Build & Upload

This guide covers building and uploading all firmware versions to your OSECHI device.

Quick Reference (v2)

task v2:build    # Build v2 firmware
task v2:upload   # Build and upload v2 to ESP32
task v2:clean    # Clean v2 build artifacts
task monitor     # Open serial monitor (115200 baud)

Check Available Versions

List all released versions (git tags):

git tag --list | sort -V

To build a specific version, use one of the following methods:

Build in a separate directory without leaving your current branch:

git worktree add ../kurikintons-v2.6.0 2.6.0
cd ../kurikintons-v2.6.0
task v2:build

Remove the worktree when done:

git worktree remove ../kurikintons-v2.6.0

Check out the tag in-place (detached HEAD state):

git checkout 2.6.0
task v2:build

Return to the latest development state when done:

git switch main

Switch to the tag explicitly in detached HEAD state:

git switch --detach 2.6.0
task v2:build

Return to the latest development state when done:

git switch main

v2 firmware is on the main branch.

git worktree add ../kurikintons-v2 2.6.0
cd ../kurikintons-v2

Detached HEAD

Worktrees created from a tag are in detached HEAD state. This is fine for building and uploading, but you cannot commit changes directly. Create a branch first if you need to make changes.

Build

task v2:build

uv run platformio run -e esp32dev-v2

A successful build prints RAM and Flash usage:

RAM:   [=         ]  14.3% (used 46880 bytes from 327680 bytes)
Flash: [===       ]  27.8% (used 363456 bytes from 1310720 bytes)

Upload

task v2:upload

uv run platformio run -e esp32dev-v2 --target upload

The device must be connected via USB. If the upload fails, check that no other process (e.g. the serial monitor) is holding the serial port open.

Monitor

task monitor

uv run platformio device monitor --baud 115200

Baud rate: 115200. Press S for status, U for uptime, H for help.

Remove Worktree

git worktree remove ../kurikintons-v2

v1 (Maintenance)

v1 firmware is on the v1 branch (maintenance only, no new features).

git worktree add ../kurikintons-v1 1.21.3
cd ../kurikintons-v1

Detached HEAD

Worktrees created from a tag are in detached HEAD state. This is fine for building and uploading, but you cannot commit changes directly. Create a branch first if you need to make changes.

Build

task v1:build

Upload

task v1:upload

Remove Worktree

git worktree remove ../kurikintons-v1

v0 (Archive)

v0 is a .ino sketch (not PlatformIO). Use git worktree to check out the archived source at tag 1.0.0 and build with arduino-cli.

git worktree add ../kurikintons-v0 1.0.0
cd ../kurikintons-v0

Detached HEAD

Worktrees created from a tag are in detached HEAD state. This is fine for building and uploading, but you cannot commit changes directly. Create a branch first if you need to make changes.

The sketch is at arduino/kurikintons_v0/kurikintons_v0.ino.

Prerequisites

Install the ESP32 board support and required libraries:

arduino-cli core install esp32:esp32
arduino-cli lib install "Adafruit Unified Sensor" "Adafruit BME280 Library" "Adafruit BusIO"

Build

arduino-cli compile \
  --fqbn esp32:esp32:esp32 \
  arduino/kurikintons_v0/kurikintons_v0.ino

Upload

Replace /dev/cu.usbserial-0001 with your device's serial port:

arduino-cli upload \
  --fqbn esp32:esp32:esp32 \
  --port /dev/cu.usbserial-0001 \
  arduino/kurikintons_v0/kurikintons_v0.ino

To find your serial port:

arduino-cli board list

Remove Worktree

git worktree remove ../kurikintons-v0

Not recommended for new projects

v0 uses the legacy 3-byte DAC binary command protocol and is kept for reference only.

Custom Build Flags

Build flags are set in platformio.ini. To override locally without modifying tracked files, create platformio.override.ini in the project root:

# platformio.override.ini
[env:esp32dev-v2]
build_flags =
    -D ENABLE_BME280=1
    -D ENABLE_TIMESTAMP=1
    -D ENABLE_HITTYPE=1
    -D ENABLE_WIFI=1
    -D ENABLE_GNSS=1

This file is automatically loaded by PlatformIO before each build and is ignored by git (see .gitignore).

Available Flags

Flag Default Description
ENABLE_BME280 1 Temperature, pressure, humidity via I2C
ENABLE_TIMESTAMP 1 uptime_ms and timedelta_us fields in output
ENABLE_HITTYPE 0 hit_type bitmask field in output
ENABLE_WIFI 0 WiFi AP mode (SSID: OSECHI-DETECTOR)
ENABLE_GNSS 0 GNSS receiver support
ENABLE_GPIO_ABSTRACTION 0 HAL-based GPIO reads instead of direct register access

For a full description of each flag, see the Build Flags Overview.

See Also