ViaText Core (Linux)#

« Back to AltGrid Project

Status: In Development
Repository: github.com/AltGrid/viatext-core

ViaText Core is the Linux-side command line and library system used for the ViaText communications project.
It allows a Linux computer to scan, manage, and message LoRa nodes directly — without phones, apps, or cloud servers.

See also Introduction to ViaText#

Overview#

ViaText is built to support human-readable communication between computers and microcontroller-based radio nodes.
It follows three design standards:

  • Simplicity — All data is readable, debuggable, and scriptable.
  • Portability — Works on almost any Linux device (PCs, Raspberry Pi, thin clients).
  • Autonomy — Fully functional offline; no external dependencies or networks.

Relationship to the Node#

  • ViaText Core (this repo) — Linux CLI and serial manager.
  • ViaText Node — ESP32 TTGO LoRa32 firmware that handles radio communication.

Together they form a two-part system:

  • Core sends and receives TLV messages over serial
  • Node processes and executes the commands via LoRa

Basic Architecture#

+------------------+       Serial/USB       +-------------------+
|  ViaText Core    |  <------------------>  |   ViaText Node    |
|  (Linux CLI)     |   SLIP-framed TLVs     |  (ESP32 + LoRa)   |
|  command_dispatch|                        |  node_interface   |
|  commands        |                        |  node_protocol    |
|  serial_io       |                        |  node_display     |
+------------------+                        +-------------------+

Build and Run#

Requirements#

  • Linux (Debian, Ubuntu, Fedora, or similar)
  • g++ with C++17 or newer
  • make

Check tools:

g++ --version
make --version

Build#

git clone https://github.com/AltGrid/viatext-core.git
cd viatext-core
make

Run Example Commands#

Scan and list connected nodes:

./viatext-cli --scan

Output:

id=N3 dev=/dev/ttyACM0 online=1
id=N20 dev=/dev/ttyACM2 online=1

Ping a node:

./viatext-cli --node N3 --ping
status=ok seq=1

Get node info:

./viatext-cli --node N3 --get all
status=ok seq=1 id=N3 alias=TestNode freq_hz=915000000 sf=7

Features Summary#

  • Human-readable TLV protocol (no JSON or Protobuf)
  • SLIP framing for reliable serial transport
  • Minimal dependencies: C++17 + CLI11 only
  • Compatible with /dev/ttyUSB* devices
  • Command and node registry system for quick device management
  • Output format designed for easy parsing and automation

Example Use Case#

# Detect and alias connected devices
./viatext-cli --scan --aliases

# Ping a device
./viatext-cli --node N3 --ping

# Rename node
./viatext-cli --node N3 --set alias FieldUnit

# Read full status
./viatext-cli --node FieldUnit --get all

Output:

status=ok seq=4 id=N3 alias=FieldUnit freq_hz=915000000 sf=7 cr=4/5

License#

MIT License — written for clarity, portability, and long-term maintenance.

ViaText

« Back to AltGrid Project