carreralib — Python interface to Carrera® DIGITAL 124/132 slotcar systems

This module provides a Python interface to Carrera® DIGITAL 124/132 slotcar systems connected via serial port or Bluetooth.

>>> from carreralib import ControlUnit
>>> cu = ControlUnit('D4:8B:C6:FC:D8:07')
>>> cu.version()
b'5331'
>>> cu.request()
Status(fuel=(15, 15, 15, 15, 15, 15, 0, 0), start=0, mode=6,
       pit=(False, False, False, False, False, False, False, False),
       display=8)
>>> cu.start()
>>> cu.request()
Status(fuel=(15, 15, 15, 15, 15, 15, 0, 0), start=1, mode=6,
       pit=(False, False, False, False, False, False, False, False),
       display=8)
>>> cu.start()
>>> cu.request()
Timer(address=1, timestamp=243019, sector=1)
>>> cu.request()
Timer(address=0, timestamp=245704, sector=1)

For Bluetooth access you will need the Carrera AppConnect® adapter, a Bluetooth Low Energy compatible device, and bluepy installed, which is only available for Linux. A serial connection should work on all platforms supported by pySerial.

Demo RMS

For demonstration purposes, the carreralib module can be used from the command line to run a simple curses-based race management system (RMS):

python -m carreralib /dev/ttyUSB0

To connect via Bluetooth, first run hcitool to discover the Carrera AppConnect® adapter’s device address:

$ sudo hcitool lescan
LE Scan ...
D4:8B:C6:FC:D8:07 Control_Unit

Then run:

python -m carreralib D4:8B:C6:FC:D8:07

Within the RMS, use the space key to start or pause a race, R to reset a race, and Q to quit.

API

The ControlUnit class encapsulates a connection to a Carrera® DIGITAL 124/132 Control Unit (CU) and provides all the features needed to implement a custom race management system (RMS).

Note that ControlUnit uses zero-based controller addresses, so 0 corresponds to controller #1, 6 is the address the autonomous car, and 7 the address of the pace car.

class carreralib.ControlUnit(device, **kwargs)

Interface to a Carrera Digital 124/132 Control Unit.

device should name a serial port, e.g. /dev/ttyUSB0 on GNU/Linux or COM3 on Windows, or the MAC address of the Carrera AppConnect® adapter. Additional keyword arguments will be passed to the underlying Connection object.

close()

Close the connection to the CU.

clrpos()

Clear all position information.

ignore(mask)

Ignore the controllers represented by bitmask mask.

request(buf='?', maxlength=None)

Send a message to the CU and wait for a response.

reset()

Reset the CU timer.

setbrake(address, value)

Set the brake value for controller address.

setfuel(address, value)

Set the fuel value for controller address.

setlap(value)

Set the current lap.

setlap_hi(value)

Set the high nibble of the current lap.

setlap_lo(value)

Set the low nibble of the current lap.

setpos(address, position)

Set the current position for controller address.

setspeed(address, value)

Set the speed value for controller address.

start()

Initiate CU start sequence.

version()

Retrieve CU version.

Connection Module

This module is mostly of interest to developers who want to create their own connection implementation, for example to use a different Bluetooth implementation.

exception carreralib.connection.BufferTooShort

“Raised when the supplied buffer is too small a message.

class carreralib.connection.Connection(device, **kwargs)

Base class for connections to a Carrera digital slotcar system.

close()

Close the connection.

recv(maxlength=None)

Return a complete message of byte data sent from the other end of the connection as a bytes object.

send(buf, offset=0, size=None)

Send byte data rom an object supporting the buffer interface as a complete message.

exception carreralib.connection.ConnectionError

The base class of all connection exceptions.

exception carreralib.connection.TimeoutError

Raised when a timeout expires.

carreralib.connection.open(device, **kwargs)

Open a connection to the given device.

Protocol Module

This module provides utility functions for dealing with the Carrera® DIGITAL 124/132 protocol.

carreralib.protocol.pack(fmt, *args)

Return a bytes object containing the arguments packed according to the format string fmt.

Similar to struct.pack(), this function performs conversion between Python values and binary protocol data. Format strings may contain the following characters:

Format	Python type	Value
B	int	unsigned byte
c	bytes of length 1	a single ASCII character
C	no value	check sum
I	int	32-bit unsigned integer
s	bytes	ASCII string
x	no value	padding/ignored
Y	int	nibble or nybble

As with struct.pack(), a format character may be preceded by an integral count. For the s format character, the count is interpreted as the length of the bytes. For the C format character, the count is interpreted as an offset in the generated buffer from which the checksum should be calculated. For the other format characters, the count is simply interpreted as a repeat count.

carreralib.protocol.unpack(fmt, buf)

Unpack from the buffer buf according to the format string fmt.

carreralib.protocol.chksum(buf, offset=0, size=None)

Compute the protocol checksum for the buffer buf.