OpenANT Python Library

The openant.base package serves as the foundational layer for the OpenANT project. It provides the core abstractions and modules required to interface with ANT USB sticks and manage communication protocols. The package is organized into several specialized submodules:

• openant.base.ant: Core ANT-specific functionality.
• openant.base.commons: Shared utility functions and common logic.
• openant.base.driver: Low-level driver interfaces for hardware communication.
• openant.base.message: Logic for handling and constructing ANT messages.

To use the openant mqtt command, you must install the mqtt extra:

pip install openant[mqtt]

Alternatively, you can install the paho-mqtt module manually. This tool requires an MQTT server.

To use the openant influx command, you must install the influx extra:

pip install openant[influx]

Alternatively, you can install the influxdb-client module manually. This tool requires an InfluxDB server version 2.0 or higher.

Install the core library via pip:

pip install openant

To install the latest development version (HEAD):

pip install git+https://github.com/Tigge/openant#egg=openant

Platform Specifics

• Linux: You must install a udev rule for the Dynastream ANTUSB stick to run without elevated privileges:

  sudo python -m openant.udev_rules

- **Windows**: Follow the [libusb driver installation instructions](https://github.com/libusb/libusb/wiki/Windows#Driver_Installation).
- **macOS**: Should work with just `libusb` installed.

To allow non-root users to access ANT USB sticks on Linux, you must install specific udev rules. This utility copies the rule file resources/42-ant-usb-sticks.rules to /etc/udev/rules.d, reloads the udev rules, and triggers the subsystem to apply changes immediately.

Requirements:

• The operating system must be Linux.
• You must run the script with root privileges (e.g., using sudo).

If you are running this as a standalone script, it will attempt to install the rules and raise an OSError if requirements are not met.

sudo python openant/udev_rules.py

The openant influx command streams DeviceData from an ANT+ device to an InfluxDB instance. This is useful for real-time plotting and post-review.

Usage Examples:

# attach to first trainer found and push data to localhost InfluxDB
openant influx --verbose FitnessDevice

# attach to power meter with device id 12345 and push to localhost InfluxDB
openant influx --id 12345 --verbose PowerMeter

# attach to devices in 'devices.json' - allows connection to multiple devices
openant influx --verbose --config devices.json config

Refer to openant influx --help for specific server setup flags.

Use the openant scan command to find nearby devices. You can filter by device type or save the results to a file.

Flags:

• --device_type: Search for specific device types.
• --outfile <path>: Save found devices to a file.
• --auto_create: Instantiate the device object when found so that device data is also printed.
• --logging: Enable logging output.

# print devices found to terminal
openant scan

# capture devices found to devices.json for use with antinflux
openant scan --outfile devices.json

# instantiate object when found so that device data is also printed
openant scan --auto_create

The install_udev_rules(raise_exception) function is the primary entry point for installing the necessary udev rules for ANT USB sticks. It checks if the platform is Linux and verifies root privileges.

Parameters:

• raise_exception (bool): If True, the function raises an OSError if the platform is not Linux or if the user lacks root privileges. If False, it prints an error message instead.

from openant.udev_rules import install_udev_rules

try:
    install_udev_rules(raise_exception=True)
except OSError as e:
    print(f"Failed to install rules: {e}")

The openant package provides access to several core modules for interacting with ANT hardware and protocols. You can import these modules directly to build your own applications:

• openant.base: Core functionality.
• openant.easy: High-level, simplified API for common tasks.
• openant.fs: ANT File System (ANT-FS) support.
• openant.devices: Device-specific implementations and management.

import openant

# Accessing modules
base = openant.base
easy = openant.easy
fs = openant.fs
devices = openant.devices

OpenANT includes a command-line interface for running various sub-commands. The CLI supports global options for logging and version information.

Global Options

• --logging: Set the logging level. Valid choices are DEBUG, INFO, WARNING, ERROR, or CRITICAL.
• --version: Display the current version of OpenANT.

Commands

Commands are implemented as sub-commands. The available commands are dynamically loaded from the subparsers directory within the package. If a specific command's dependencies are missing, the CLI will report that the command is unavailable rather than crashing.

# Example: Set logging level to DEBUG
python -m openant --logging DEBUG <command> [args]

# Example: Check version
python -m openant --version

The openant package provides a command-line interface (CLI) for interacting with ANT USB sticks and managing device data. You can invoke the CLI directly using the openant command if the package is installed in your environment's path, or via python -m openant.

python -m openant [COMMAND]