Tracked Robot Control Studio & Telemetry Monitor

botracked is a modular Python desktop application, telemetry monitor, and mission scripting suite for tracked robotic platforms.

Developed in python code.

The README is used to introduce the modules and provide instructions on how to install the modules, any machine dependencies it may have and any other information that should be provided before the modules are installed.

Table of Contents

• 🚀 Installation
  • Install using pip
  • Install using build
  • Install using py setup
  • Install using docker
• 📦 Dependencies
• 📁 Tool structure
  • 🏗 Architecture & SOLID Principles
    • SOLID Principles Compliance
    • Automated Quality Gates (run_quality_gates.sh)
  • ✨ Features
  • 📜 Tracked Bot Domain-Specific Language (DSL) & .track Programs
    • Tracked Bot DSL Instruction Reference
    • Example .track Program: Autonomous Perimeter Patrol
  • 📡 Binary Packet Communication Protocol & Framing
    • Command Frames (PC $\to$ Robot)
    • Telemetry Frames (Robot $\to$ PC)
• 📊 Code coverage
• 🛠 Usage
  • CLI Command Options
  • Interactive Mission Planning & Telemetry Workflow
• 📚 Docs
• 👥 Contributing
• 📄 Copyright and licence

🚀 Installation

Used next development environment

Currently there are three ways to install package

• Install process based on using pip mechanism
• Install process based on build mechanism
• Install process based on setup.py mechanism
• Install process based on docker mechanism

Install using pip

botracked is located at pypi.org.

You can install by using pip

# python3
pip3 install botracked

Install using build

Navigate to release page download and extract release archive.

To install botracked type the following

tar xvzf botracked-x.y.z.tar.gz
cd botracked-x.y.z/
# python3
wget https://bootstrap.pypa.io/get-pip.py
python3 get-pip.py 
python3 -m pip install --upgrade setuptools
python3 -m pip install --upgrade pip
python3 -m pip install --upgrade build
pip3 install -r requirements.txt
python3 -m build --no-isolation --wheel
pip3 install ./dist/botracked-*-py3-none-any.whl
rm -f get-pip.py
chmod 755 /usr/local/lib/python3.10/dist-packages/usr/local/bin/botracked_run.py
ln -s /usr/local/lib/python3.10/dist-packages/usr/local/bin/botracked_run.py /usr/local/bin/botracked_run.py

Install using py setup

Navigate to release page download and extract release archive.

To install botracked locate and run setup.py with arguments

tar xvzf botracked-x.y.z.tar.gz
cd botracked-x.y.z
# python3
pip3 install -r requirements.txt
python3 setup.py install_lib
python3 setup.py install_egg_info

Install using docker

You can use Dockerfile to create image/container.

📦 Dependencies

botracked requires next modules and libraries

• ats-utilities - Python App/Tool/Script Utilities
• pyserial - Python Serial Port Extension

📁 Tool structure

botracked is based on OOP and Clean Architecture.

Tool structure

    botracked/
         ├── core/
         │   ├── __init__.py
         │   ├── model/
         │   │   ├── connection_params.py
         │   │   ├── dsl/
         │   │   │   ├── ast_instruction.py
         │   │   │   ├── compiled_step.py
         │   │   │   ├── __init__.py
         │   │   │   ├── token.py
         │   │   │   └── token_type.py
         │   │   ├── __init__.py
         │   │   ├── motion_command.py
         │   │   ├── protocol_opcode.py
         │   │   └── telemetry_data.py
         │   └── service/
         │       ├── bot_motion_service.py
         │       ├── bot_service.py
         │       ├── bot_telemetry_service.py
         │       ├── communication/
         │       │   ├── ibinary_codec.py
         │       │   ├── ibot_transport.py
         │       │   ├── icrc8_calculator.py
         │       │   ├── __init__.py
         │       │   └── itelemetry_observer.py
         │       ├── dsl/
         │       │   ├── __init__.py
         │       │   ├── itbot_compiler.py
         │       │   ├── itbot_dsl_service.py
         │       │   ├── itbot_lexer.py
         │       │   ├── itbot_parser.py
         │       │   ├── tbot_compiler.py
         │       │   ├── tbot_dsl_service.py
         │       │   ├── tbot_lexer.py
         │       │   └── tbot_parser.py
         │       ├── ibot_connection_service.py
         │       ├── ibot_mission_service.py
         │       ├── ibot_motion_service.py
         │       ├── ibot_service.py
         │       ├── ibot_telemetry_service.py
         │       ├── __init__.py
         │       ├── mission_runner.py
         │       └── telemetry_poller.py
         ├── engine.py
         ├── infrastructure/
         │   ├── cli/
         │   │   ├── engine.py
         │   │   ├── icli.py
         │   │   ├── __init__.py
         │   │   └── setup/
         │   │       ├── bundle.py
         │   │       ├── dep_validator.py
         │   │       ├── dependencies.py
         │   │       ├── factory.py
         │   │       ├── __init__.py
         │   │       ├── keys.py
         │   │       ├── opt_validator.py
         │   │       ├── options.py
         │   │       ├── registry.py
         │   │       └── validator.py
         │   ├── command/
         │   │   ├── command.py
         │   │   ├── icommand_definition.py
         │   │   ├── icommand_executor.py
         │   │   ├── __init__.py
         │   │   ├── studio_command_definition.py
         │   │   └── studio_command_executor.py
         │   ├── communication/
         │   │   ├── binary_codec.py
         │   │   ├── crc8_calculator.py
         │   │   ├── __init__.py
         │   │   ├── preferences/
         │   │   │   ├── connection_preferences_repository.py
         │   │   │   └── __init__.py
         │   │   ├── serial_transport.py
         │   │   └── tcp_transport.py
         │   ├── config/
         │   │   ├── botracked.cfg
         │   │   ├── botracked.logo
         │   │   └── scheme.json
         │   ├── gui/
         │   │   ├── connection/
         │   │   │   ├── connection_callbacks.py
         │   │   │   ├── connection_panel.py
         │   │   │   ├── connection_panel_config.py
         │   │   │   └── __init__.py
         │   │   ├── controls/
         │   │   │   ├── __init__.py
         │   │   │   ├── jog_panel.py
         │   │   │   ├── jog_panel_callbacks.py
         │   │   │   └── jog_panel_config.py
         │   │   ├── editor/
         │   │   │   ├── dsl_editor_panel.py
         │   │   │   ├── dsl_editor_panel_config.py
         │   │   │   ├── dsl_preset_loader.py
         │   │   │   ├── dsl_syntax_highlighter.py
         │   │   │   ├── dsl_syntax_highlighter_config.py
         │   │   │   ├── __init__.py
         │   │   │   └── mission_callbacks.py
         │   │   ├── engine.py
         │   │   ├── gui_config.py
         │   │   ├── gui_event_mediator.py
         │   │   ├── igui.py
         │   │   ├── __init__.py
         │   │   ├── stream/
         │   │   │   ├── __init__.py
         │   │   │   ├── log_panel.py
         │   │   │   └── log_panel_config.py
         │   │   ├── telemetry/
         │   │   │   ├── __init__.py
         │   │   │   ├── telemetry_panel.py
         │   │   │   └── telemetry_panel_config.py
         │   │   └── theme/
         │   │       ├── colors.py
         │   │       ├── __init__.py
         │   │       └── style.py
         │   └── __init__.py
         ├── __init__.py
         └── setup/
             ├── bundle.py
             ├── dep_validator.py
             ├── dependencies.py
             ├── factory.py
             ├── __init__.py
             ├── keys.py
             ├── opt_validator.py
             ├── options.py
             ├── registry.py
             └── validator.py

     22 directories, 107 files

🏗 Architecture & SOLID Principles

botracked is built on a strictly decoupled, Layered Clean Architecture where presentation, domain logic, AST compilation, and hardware communication are segregated through pure Python protocols:

                  ┌─────────────────────────────────────────────────────────┐
                  │                       BotrackedGUI                      │ (Presenter / Main Window)
                  └────────────────────────────┬────────────────────────────┘
                                               │ Mediates UI Events via GUIEventMediator
         ┌─────────────────────────┬───────────┴─────────────┬──────────────────────────┐
         ▼                         ▼                         ▼                          ▼
┌──────────────────┐      ┌─────────────────┐      ┌───────────────────┐      ┌──────────────────┐
│ ConnectionPanel  │      │    JogPanel     │      │   DSLEditorPanel  │      │  TelemetryPanel  │
│(Serial / TCP/IP) │      │(D-Pad Controls) │      │ (Script & Runner) │      │ (Gauges & Faults)│
└────────┬─────────┘      └────────┬────────┘      └─────────┬─────────┘      └────────┬─────────┘
         │                         │                         │                         │
         └────────────┬────────────┴─────────────────────────┴─────────────────────────┘
                      │ Observes / Commands IBotService
                      ▼
         ┌──────────────────────────┐
         │        BotService        │ (Application Facade / Coordinator)
         └────────────┬─────────────┘
                      │
         ┌────────────┴────────────┬────────────────────────┬──────────────────────────┐
         ▼                         ▼                        ▼                          ▼
┌──────────────────┐      ┌──────────────────┐     ┌─────────────────┐        ┌──────────────────┐
│ BotMotionService │      │BotTelemetryServ. │     │ MissionRunner   │        │   TBotDslService │
│(Kinematic Drive) │      │ (State & Poller) │     │ (Step Execution)│        │ (Lexer & Parser) │
└────────┬─────────┘      └────────┬─────────┘     └────────┬────────┘        └────────┬─────────┘
         │                         │                        │                          │
         └────────────┬────────────┴────────────────────────┘                          ▼
                      │ Dispatches Packets via IBotTransport                  ┌──────────────────┐
                      ▼                                                       │   TBotCompiler   │
         ┌──────────────────────────┐                                         └──────────────────┘
         │  Serial / TCP Transport  │
         └────────────┬─────────────┘
                      │ Frames Packets via IBinaryCodec & ICrc8Calculator
                      ▼
         ┌──────────────────────────┐
         │ BinaryCodec & CRC8 Calc  │
         └──────────────────────────┘

SOLID Principles Compliance

• S — Single Responsibility Principle (SRP):
  • Every module and class has exactly one clearly bounded reason to change.
  • Parser, lexer, and compiler logic is decomposed into dedicated handlers (TBotLexer, TBotParser, TBotCompiler, TBotDslService) rather than a monolithic interpreter.
  • GUI tabs are decomposed into panel configs, callbacks, and layout managers.
  • Enforced by automated gate: strict limit of $\le 15$ methods per class across the entire codebase.
• O — Open/Closed Principle (OCP):
  • The DSL parser, compiler, and binary codec are open for extension without modifying existing code.
  • New motion opcodes and instructions plug into dedicated registries dynamically.
• L — Liskov Substitution Principle (LSP):
  • Pure structural subtyping via Python @runtime_checkable Protocol definitions. Concrete classes never inherit concrete logic, ensuring complete interchangeability.
• I — Interface Segregation Principle (ISP):
  • Clients depend only on the minimal interfaces they require (IBotService, IBotMotionService, IBotTelemetryService, IBotTransport, IBinaryCodec, ICrc8Calculator).
• D — Dependency Inversion Principle (DIP):
  • Core domain entities and services have zero dependencies on lower-level infrastructure (pyserial drivers, sockets, UI widgets). All dependencies are injected via protocols.

Automated Quality Gates (run_quality_gates.sh)

Every build is validated against 4 strict automated quality gates:

1. Structural Protocols Gate: Verifies 100% compliance with @runtime_checkable Protocol structural typing.
2. Interface Segregation Gate (ISP): Verifies that no bloated or unused interfaces exist.
3. Module Limits Gate: Enforces file length ($\le 300$ lines) and line length limits ($\le 100$ characters).
4. Single Responsibility Gate (SRP): Strictly enforces $\le 15$ methods per class.

✨ Features

• Dual Transport Support: Multi-channel USB Serial (/dev/ttyUSB0 @ 115200 baud) and low-latency TCP Socket (127.0.0.1:8888 or WiFi IP) streaming.
• Interactive Jog & Navigation Cockpit: Real-time D-Pad buttons for Forward, Backward, Skid-Turns, In-Place Spins, and instant Emergency Stop with keyboard key bindings (W, A, S, D, Q, E, Space).
• Tracked Robot Mission DSL (.track): Full declarative scripting pipeline featuring lexical tokenizer, syntax parser, AST builder, and binary opcode compiler with Step, Run, Pause, and Resume execution controls.
• Real-Time Telemetry Dashboard: Live monitoring of system operational mode (NORMAL, DEGRADED, PANIC), kinematic track speeds, hardware fault counters, motor lock status, and round-trip ping latency.
• Terminal Packet Inspector: Bi-directional packet visualizer logging raw TX/RX frames with sequence counters, opcode labels, hex payloads, and CRC-8 integrity verification.
• Robust CRC-8 Dallas/Maxim Codec: High-integrity binary packet framing protocol with start-of-frame synchronization, opcode mapping, dynamic payload lengths, and checksum verification.
• Strict Quality & SOLID Standards: 100% protocol conformity, zero ISP/SRP violations, $\ge 78%$ test coverage, and 10.00 / 10.00 Pylint score.

📜 Tracked Bot Domain-Specific Language (DSL) & .track Programs

botracked includes a dedicated Domain-Specific Language designed specifically for tracked mobile robots. Programs are written in plain text files with the .track extension:

                    ┌─────────────────────────┐
                    │      .track Source      │
                    └────────────┬────────────┘
                                 │ TBotLexer
                                 ▼
                    ┌─────────────────────────┐
                    │      Token Stream       │
                    └────────────┬────────────┘
                                 │ TBotParser
                                 ▼
                    ┌─────────────────────────┐
                    │      Abstract AST       │
                    └────────────┬────────────┘
                                 │ TBotCompiler
                                 ▼
                    ┌─────────────────────────┐
                    │      Compiled Steps     │ (Binary Packets & Delays)
                    └─────────────────────────┘

Tracked Bot DSL Instruction Reference

Example .track Program: Autonomous Perimeter Patrol

# ----------------------------------------------------
# Autonomous Perimeter Patrol Mission
# ----------------------------------------------------
SPEED 180
PING
WAIT 200ms

# Leg 1: Drive forward along north boundary
FORWARD 3.0s
WAIT 500ms

# Rotate 90 degrees right in place
SPIN_RIGHT 1.2s
WAIT 300ms

# Leg 2: Drive forward along east boundary
FORWARD 3.0s
WAIT 500ms

# Rotate 90 degrees right in place
SPIN_RIGHT 1.2s
WAIT 300ms

# Leg 3: Return to home position
FORWARD 3.0s
STOP
CLEAR_ERRORS

📡 Binary Packet Communication Protocol & Framing

All communication between botracked and the physical or virtual robot uses a framed binary protocol protected by Dallas/Maxim CRC-8:

• Frame Layout: [0xAA] [0x55] [OPCODE] [LEN] [PAYLOAD...] [CRC8]
• Header: 0xAA 0x55 (Start of Frame synchronization marker).
• Opcode: 1-byte command or response identifier.
• Length: 1-byte payload length ($0 \dots 255$).
• Payload: Raw parameter bytes corresponding to opcode.
• CRC-8: Computed over OPCODE + LEN + PAYLOAD using polynomial $x^8 + x^5 + x^4 + 1$ (0x31, init 0x00).

Command Frames (PC $\to$ Robot)

Telemetry Frames (Robot $\to$ PC)

📊 Code coverage

🛠 Usage

Install package

pip3 install botracked

Prepare main entry point by downloading main.py or create your own.

wget -O main.py https://raw.githubusercontent.com/vroncevic/botracked/main/main.py

CLI Command Options

Launch the graphical studio with default configuration:

python3 main.py studio

Launch with initial mission script and verbose logging:

python3 main.py studio --file ./missions/patrol_demo.track --verbose enable

Interactive Mission Planning & Telemetry Workflow

1. Connect to Robot Platform:
   • Under the Connection panel, select your transport mode:
     • Serial USB: Select port (e.g. /dev/ttyUSB0) and baudrate (115200).
     • TCP / Network: Enter the robot IP address (e.g. 192.168.4.1 or 127.0.0.1) and port (8888).
   • Click Connect. The status bar reflects connection state and initializes the telemetry polling loop.
2. Manual Jog Cockpit:
   • Navigate using the interactive D-Pad buttons or keyboard shortcuts (W, A, S, D, Q, E, Space).
   • Adjust drive speed smoothly with the PWM slider ($60 \dots 255$).
3. Mission Scripting:
   • Open the Mission Studio panel.
   • Write or select a bundled .track mission program from the Preset dropdown.
   • Click Validate to verify syntax with the AST parser.
   • Click Run Mission for automated execution, or use Step for single-instruction stepping.
4. Telemetry & Log Inspection:
   • Observe active system modes, track PWMs, error codes, and ping latency on the Telemetry gauges.
   • Monitor real-time TX/RX binary packets with timestamps and hex payloads in the Terminal Log.

📚 Docs

More documentation and info at

• botracked.readthedocs.io
• www.python.org

👥 Contributing

Contributing to botracked

📄 Copyright and licence

Copyright (C) 2026 by vroncevic.github.io/botracked

botracked is free software; you can redistribute it and/or modify it under the same terms as Python itself, either Python version 3.x or, at your option, any later version of Python 3 you may have available.

Special thanks to Google and the Google developer ecosystem for their tremendous support and innovative tools from the Google bundle that empowered the development and realization of this project. Google, you make this world a better place! 🌍✨

Lets help and support PSF.