# Introduction to Viatext Core

An introduction to ViaText Core, a Linux command-line and library project for managing and messaging LoRa nodes, with architecture, build instructions, and example commands.

2025-10-20
::
Leo Blanchette


![Introduction to Viatext Core](https://switchboardtechservices.com/media/assets/2026/09/viatux-looking-down-at-terminal.jpg)

## Contents

- [ViaText Core (Linux)](https://switchboardtechservices.com/articles/introduction-to-viatext-core/#viatext-core-linux)
  - [See also Introduction to ViaText](https://switchboardtechservices.com/articles/introduction-to-viatext-core/#see-also-introduction-to-viatext)
  - [Overview](https://switchboardtechservices.com/articles/introduction-to-viatext-core/#overview)
  - [Relationship to the Node](https://switchboardtechservices.com/articles/introduction-to-viatext-core/#relationship-to-the-node)
  - [Basic Architecture](https://switchboardtechservices.com/articles/introduction-to-viatext-core/#basic-architecture)
  - [Build and Run](https://switchboardtechservices.com/articles/introduction-to-viatext-core/#build-and-run)
    - [Requirements](https://switchboardtechservices.com/articles/introduction-to-viatext-core/#requirements)
    - [Build](https://switchboardtechservices.com/articles/introduction-to-viatext-core/#build)
    - [Run Example Commands](https://switchboardtechservices.com/articles/introduction-to-viatext-core/#run-example-commands)
  - [Features Summary](https://switchboardtechservices.com/articles/introduction-to-viatext-core/#features-summary)
  - [Example Use Case](https://switchboardtechservices.com/articles/introduction-to-viatext-core/#example-use-case)
  - [License](https://switchboardtechservices.com/articles/introduction-to-viatext-core/#license)

# ViaText Core (Linux)

[<< Back to AltGrid Project](https://switchboardtechservices.com/projects/altgrid/)

**Status:** In Development  
**Repository:** [github.com/AltGrid/viatext-core](https://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](https://switchboardtechservices.com/projects/altgrid/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](https://switchboardtechservices.com/media/assets/2026/09/viatext.jpg)

[<< Back to AltGrid Project](https://switchboardtechservices.com/projects/altgrid/)

[Articles RSS](https://switchboardtechservices.com/feeds/articles.xml "Subscribe using an RSS reader")

---

Canonical URL: https://switchboardtechservices.com/articles/introduction-to-viatext-core/

Language: en-us

Content type: article

Author: Leo Blanchette

Published: 2025-10-20T22:04:02+00:00

Modified: 2025-10-20T22:04:02+00:00