Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

AceLight

Python client for the AceLight CAN protocol, developed by AceHigh ApS.
For more information and documentation of the protocol please visit acelight.

Start commanding stepper motors with the Ranger Mk1 module and acelight. Ranger Mk1.

Read and write device parameters through a small synchronous API. The package includes a parameter table for the hardware module Ranger Mk1 and uses python-can for the CAN interface.

This is an alpha release. The API and device parameter tables may change.

Requirements

  • Python 3.9 or newer.
  • A CAN adapter supported by python-can. The example below uses SLCAN over a serial port. The CANable 2.0 CAN analyzer USB to CAN adapter has been tested and confirmed working on Mac OS.
  • A hardware module running compatible AceLight firmware. Parameter IDs and data types must match the device firmware. See the specific device datasheet for complete list of parameters.

The package dependency python-can[serial] includes the serial support used by the example. Other CAN interfaces may require their own drivers or dependencies.

Installation

For an alpha release published on PyPI:

python -m pip install --pre acelight

For development, run the following from the directory containing pyproject.toml:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

On Windows, activate the environment with .venv\Scripts\Activate.ps1 in PowerShell instead of the source command.

Quick start

Set the adapter channel, CAN bitrate, host ID, and device node ID for your setup. SLCAN channel names typically look like /dev/cu.usbmodem... on macOS, /dev/ttyACM0 on Linux, or COM4 on Windows.

import can
import acelight
from acelight.client import ACE_STATUS_DATA_FOLLOWS, ACE_STATUS_OK
from acelight.modules import ranger_mk1_param as r

CHANNEL = "/dev/cu.usbmodem..."  # Replace with your adapter's serial port.
BITRATE = 1_000_000
HOST_ID = 1
NODE_ID = 2

with can.Bus(interface="slcan", 
            channel=CHANNEL, 
            bitrate=BITRATE) 
            as bus:

    ace = acelight.Client(HOST_ID, bus)

    status = ace.write(NODE_ID, r.profile_velocity, 10000) # set steps/second 
    print(f"Write status: 0x{status:02X}") # status code 0x01 means write was accepted by the HW module

    for i in range(5):
        status, temperature = ace.read(NODE_ID, r.temperature) # read temperature, units in milli degrees.
        print(f"Read status: {status}")
        print(f"Temperature data. {temperature})

This example writes the motion profile velocity once and reads back temperature five times. It does not issue a move command.

Parameter values are raw integers. Check the device documentation for units and scaling; the client does not automatically convert values into engineering units.

See more python examples under acelight github repository.

API

Client

ace = acelight.Client(host_id=1, bus=bus)

Pass an already configured python-can bus. The application creates and closes the bus; the example uses a context manager for this.

Read a parameter

status, value = ace.read(node_id, parameter)
  • On a response with status ACE_STATUS_DATA_FOLLOWS, returns (status, decoded_value).
  • On another response status, returns (status, None).
  • If no message arrives during a receive wait, raises TimeoutError.

Write a parameter

status = ace.write(node_id, parameter, value)

Returns the device's response status. If no message arrives during a receive wait, raises TimeoutError.

The application decides how to handle device status codes and exceptions. A caught timeout does not automatically retry a request.

Parameters

Ranger Mk1 definitions are in acelight/src/modules/ranger_mk1_param.py. Each Parameter contains the protocol parameter ID and its data type.

Supported types are U8, U16, I16, U32, and I32. Multi-byte values use little-endian encoding.

The current Ranger table is a subset of the device parameters. Use only definitions that match the connected device firmware.

Response status codes

These constants are available from acelight.client.

Constant Value
ACE_STATUS_OK 0x01
ACE_STATUS_DATA_FOLLOWS 0x02
ACE_STATUS_INVALID_PARAMETER 0x03
ACE_STATUS_INVALID_VALUE 0x04
ACE_STATUS_READ_ONLY 0x05
ACE_STATUS_WRITE_ONLY 0x06
ACE_STATUS_NODE_BUSY 0x07

Current scope

Requests are synchronous. Use one request at a time and give the client sole ownership of reception from its bus object. The request loop consumes unrelated messages while waiting for its response.

The receive timeout is currently one second per bus.recv() call. Unrelated traffic can extend the total request duration. The client does not automatically retry requests.

The current implementation assumes correctly formed device responses. Empty or incorrectly sized payloads can raise IndexError or struct.error.

Metadata

Release files for acelight 0.0.0a1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for acelight 0.0.0a1
File Size Uploaded Provenance Actions
acelight-0.0.0a1.tar.gz 9.3 kB Without provenance Details for acelight-0.0.0a1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for acelight 0.0.0a1
File Interpreter ABI Platform Actions
acelight-0.0.0a1-py3-none-any.whl Python 3 none any Details for acelight-0.0.0a1-py3-none-any.whl

Total release size: 17.2 kB

Release files / acelight-0.0.0a1.tar.gz

Download URL acelight-0.0.0a1.tar.gz
Size 9.3 kB
Tags Source
SHA-256 checksum
How to use checksums
4c3cfb6241585293993c6638ada52282baa4da7347fab925e3dbb66333846767
BLAKE2b-256 checksum
How to use checksums
001deb2f8ac5d97991551d823bfcf05afe248fce4e0347e90cc83c46bb4cc8c4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.6

Release files / acelight-0.0.0a1-py3-none-any.whl

Download URL acelight-0.0.0a1-py3-none-any.whl
Size 7.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
10676de99d3429c8a5e92093874e230d5fda5ee330bb0ada7b845cc7afd05e7a
BLAKE2b-256 checksum
How to use checksums
ee00c17176f3c8e57c136d7f13741480ba5e6de3258b09d133a37bb6f66bf630
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.6

Security for acelight 0.0.0a1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page