__
.--------.-----.-----.|  |--.----.-----.----.-----.
|        |  -__|__ --||     |  __|  _  |   _|  -__|
|__|__|__|_____|_____||__|__|____|_____|__| |_____|


== flash firmware via terminal ==

This guide only works on Espressif (ESP) devices

- download firmware via flasher site [4] TODO: show how to download via GitHub cli

```
# identify device and serial port that it's attached to
$ uvx esptool chip-id

esptool v5.4.0
Connected to ESP32-S3 on /dev/ttyACM0:
Chip type:          ESP32-S3 (QFN56) (revision v0.2)
Features:           Wi-Fi, BT 5 (LE), Dual Core + LP Core, 240MHz, Embedded PSRAM 8MB (AP_3v3)
Crystal frequency:  40MHz
USB mode:           USB-Serial/JTAG
MAC:                RE:DA:CT:ED

Stub flasher running.

WARNING: ESP32-S3 has no chip ID. Reading MAC address instead.
MAC:                RE:DA:CT:ED

Hard resetting via RTS pin...

# never hurts to verify this is the right serial port
$ uvx meshcore-cli -l
BLE devices:

Serial ports:
 /dev/ttyACM0       USB JTAG/serial debug unit [USB VID:PID=303A:1001 SER=RE:DA:CT:ED LOCATION=1-1:1.0]

# flash
uvx esptool --port /dev/ttyACM0 write-flash 0x10000 /some/path/to/your/firmware.bin

# verify
uvx esptool --port /dev/ttyACM0 chip-id
```

== companion cli cheatsheet ==

source: [5]

```
# ffs
/clock sync

# show repeaters and SNR on each message
/set channel_echoes on

# chat to hashtag channel
/to #some-channel

# login into repeater
/login RPT PASSWORD 😬

# repeater's neighbors
/req_neighbours RPT

# repeater trace route
/trace contact-1,contact-2,contact-n,contact-2,contact-1

# removes all clients that have not been updated in last 2 days
at u<2d,t=1 remove_contact
```

== meshcore radio serial companion configuration ==

the easiest way i've found to set up a meshcore[1] 
is to flash the device as a bluetooth companion. 
configure the name, lora preset and other bits
using the companion app. then you can reflash as
a serial companion.

this is one thing i miss from meshtastic, in that
ecosystem you can configure you radio to link via
bluetooth serial and WiFi (if you have the 
capability).

before you install any software, i would recommend
you verify the serial link works by using the 
meshcore cli[2], you can also use this tool to 
test bluetooth, but the bot software i'm using
doesn't support bluetooth (just serial and tcp).

>> pro-tip: use meshcore-cli -S to connect to 
>> bluetooth devices, the device details will be
>> cached for future use. so you only need to do 
>> this once.

-- y tho? --

when you have a small or sparse mesh (terminology
for a mesh network) it's handy to have something
that automatically responds to messages. if 
you've ever used the ping command you know what
i'm talking about.

-- software --

i'm currently evaluating volley[3]

we'll assume you've run meshcore-cli -l and your
serial device is /dev/ttyUSB0. also we're using
astral's excellent uv to manage pythonic 
concerns.

```
gh repo gretel/volley
cd volley
uv sync
python main.py -s /dev/tttUSB0
```

>> pro-tip: if uv fails to find a suitable version 
>> of python try: uv python install 3.14

then, DM you bot and send "ping"

== references ==

[1] https://meshcore.io
[2] https://github.com/meshcore-dev/meshcore-cli
[3] https://github.com/gretel/volley
[4] https://flasher.meshcore.io/
[5] https://github.com/meshcore-dev/meshcore-cli#interactive-mode