ThingBot Telemetrix

ThingBot Telemetrix provides a Python API and an Arduino companion library for controlling ThingBot over the Telemetrix protocol. Use this repository to script sensors and actuators from Python or run Arduino firmware that speaks Telemetrix.

Highlights

• Lightweight Python API for digital, analog/PWM, DHT, ultrasonic, servo and DC motor control
• Example Python scripts in examples/
• Arduino library and example firmware in thingbot-telemetrix-arduino/

Repository layout

• thingbot_telemetrix/ — Python package: core API and handlers
• examples/ — Example Python scripts (blink.py, dht_input.py, ultrasonic_distance.py)
• thingbot-telemetrix-arduino/ — Arduino library and PlatformIO example

Requirements

• Python 3.9 or newer
• A ThingBot-compatible board running Telemetrix or compatible firmware
• Serial (USB) or network access to the board

Flash firmware

To flash ThingBot board with Telemetrix firmware, there are 2 option for this:

1. Use meo-tool cli tool to flash telemetrix firmware.

• First, install the Python cli tool meo-tool:

pip install meo-tool

• Then, use meo-tool to flash the firmware:

meo-tool flash thingbot-telemetrix --latest --auto-detect

2. Use PlatformIO/Arduino IDE to build and flash the firmware from the thingbot-telemetrix-arduino/ repository. Open the folder in PlatformIO, select the appropriate board and port, and build/flash the firmware.

• thingbot-telemetrix-arduino GitHub repository
• PlatformIO project: thingbot-telemetrix-arduino/platformio.ini contains build configurations for supported boards.
• Arduino IDE: thingbot-telemetrix-arduino/src/main.cpp defines the board-side handling for the Telemetrix protocol.
• Or choose the pre-compiled firmware binary from the releases page and flash it using your preferred method (e.g. esptool.py for ESP32).

Installation

Install the Python package for development:

pip install thingbot-telemetrix

Quickstart (Python)

Import and connect to a board (API names are illustrative — check package docstrings):

from thingbot_telemetrix import Telemetrix

# Example: open serial port and connect
board = Telemetrix('/dev/ttyUSB0')  # Adjust port as needed or None for auto-detect

# Digital write
board.gpio().digital_write(13, 1)

# PWM write
board.gpio().analog_write(5, 128)

# Register analog input callback
def on_analog(value):
	print('Analog:', value)

board.gpio().set_pin_mode_analog_input(0, callback=on_analog)

Actuators & Sensors

• control_dc(channel, speed) — control a DC motor channel (speed range depends on firmware)
• control_servo(index, position) — set servo position (commonly 0–180)
• set_pin_mode_dht(pin, callback, dht_type) — read DHT11/DHT22 sensors
• Ultrasonic distance via set_pin_mode_ultrasonic(...) and read_ultrasonic() on board.ultrasonic()

Arduino firmware

The thingbot-telemetrix-arduino/ folder contains a PlatformIO project and an Arduino library ThingBotTelemetrixArduino that implements board-side handling for the Telemetrix protocol. Open the folder in PlatformIO to build and flash the firmware.

Examples

• examples/blink.py — blink an onboard LED
• examples/dht_input.py — sample DHT sensor reader
• examples/thingbot_switch.py — example ThingBot switch handler
• examples/ultrasonic_distance.py — example ultrasonic distance reader

Contributing

Contributions are welcome. Please open issues for bugs or feature requests and send PRs for fixes or enhancements. Keep changes focused and include tests/examples when appropriate.

License

This project is provided under the GNU Affero General Public License v3 (AGPL-3.0-or-later). See LICENSE for details.

Handler API

This section documents the Python-side handler APIs available from a Telemetrix instance. Use these handlers to control pins, read sensors, and interact with ThingBot-specific hardware features.

• Access handlers: obtain handlers from a Telemetrix instance:

# package-level import
from thingbot_telemetrix import Telemetrix

board = Telemetrix()
gpio = board.gpio()
dht = board.dht()
thingbot = board.thingbot()
ultrasonic = board.ultrasonic()

• GpioHandler (gpio)

  • set_pin_mode_output(pin_number) — set a digital output.
  • set_pin_mode_digital_input(pin_number, callback=None) — set a digital input and optionally register a callback callback(value) where value is 0 or 1.
  • set_pin_mode_analog_input(pin_number, differential=0, callback=None) — set an analog input; differential is a threshold and callback(value) receives a 0–1023 integer value.
  • digital_write(pin_number, value) — write digital 0/1.
  • analog_write(pin_number, value) — write PWM 0–255.
  • digital_read(pin_number) — request a single digital read.
  • analog_read(pin_number) — request a single analog read.

  Example: register an analog callback

   def on_analog(value):
   		print('Analog:', value)
  
   gpio.set_pin_mode_analog_input(0, differential=10, callback=on_analog)

• DhtHandler (dht)

  • set_pin_mode_dht(pin_number, dht_type, callback=None) — enable DHT on a pin. dht_type is DHTTypes.DHT11 or DHTTypes.DHT22. If callback is provided it will be called as callback(temperature, humidity) where values are floats (temperature in °C, humidity in %).

  Example:

   from thingbot_telemetrix.private_constants import DHTTypes
  
   def on_dht(temp, hum):
   		print(f'Temp={temp}°C Hum={hum}%')
  
   dht.set_pin_mode_dht(2, DHTTypes.DHT22, callback=on_dht)

• ThingBotHandler (thingbot)

  • control_buzzer(frequency) — set buzzer frequency (0 to turn off).
  • control_led(led_number, state) — set LED brightness (0–100 typical).
  • control_dc(motor_number, speed) — control DC motor speed (signed value, e.g. -100..100).
  • control_servo(servo_number, angle) — set servo position (0–180).
  • set_sw_callback(callback) — register a switch callback callback(pressed) where pressed is True when pressed, False when released.

  Example: set switch callback

   def on_switch(pressed):
   		print('Switch pressed' if pressed else 'Switch released')
  
   thingbot.set_sw_callback(on_switch)

• UltrasonicHandler (ultrasonic via board.ultrasonic())

  • set_pin_mode_ultrasonic(trigger_pin, echo_pin, callback=None) — enable ultrasonic sensing and register a callback callback(distance, trigger_pin, echo_pin).
  • read_ultrasonic() — request a single ultrasonic distance measurement.

For more details check the handler source files in thingbot_telemetrix/handler/.

---

For detailed API docs, view the docstrings in the thingbot_telemetrix package or open the examples for usage patterns.