Advanced Usage

The script presented in getting started is is working but somehow limiting, in this section

Events

The library exposes the class Events as events instance variable. All available events are attributes of the events instance. To link an event ‘’Signal’’ to a slot:

import oxigenlib as o2
...
@o2.events.new_lap_event.connect
def do_something(*args):
    print(args)

List of available events:

Note

The library does not implement yet all the event that oxigen protocol identifies. Extension of events is planned for future releases

new_lap_event(int, int, int, float, bool) raised when new lap event occur
parameters: [car id / car_laps_count / timestamp in centiseconds / laptime in seconds / info_flag]

pit_lane_enter_event(int, int) raised when a car enter the pit lane
parameters: [car id / timestamp in centiseconds]

pit_lane_leave_event(int, int) raised when a car leaves the pit lane
parameters: [car id / timestamp in centiseconds]

track_call_event(bool, list) track button was pressed
parameters: [flag true-false / list of car ids with track call button pressed]

all_cars_on_track_event(bool, list) flag raised when at least one car deslotted or when all cars are back on track
parameters: [flag true-false / list of car ids off-track]

The following events are also available but created for internal used. Only for advanced users.

dongle_flush_cache()
parameters: n/a

dongle_connected_event(bool) raised after a connect attempt, returns the result of the connection attempt
parameters: [flag true-false]

transmit_command_event(bytes) data ready to be sent to the dongle, payload attached
parameters: [bytes with data payload]

dongle_new_data_available_event(DongleRxData) data package received from the dongle, the payload is already converted into a DongleRxData class
parameters: [DongleRxData]

Utilities

Utility functions are available to send specific commands to the dongle, all functions are accessible for simplificity are directly available in the oxigenlib name space.

So for example the set_system_max_speed utility function can be called as follows:

import oxigenlib as o2
...
o2.set_system_max_speed(max_speed, system, timer)

Initial config

set_start_config is the starting point, it creates an OxigenSystem configuration:

oxigenlib.set_start_config(max_speed: int, pit_lane_trigger: PitLaneTrigger, pit_lane_count: PitLaneCount, power_mean_value: PowerMeanValue) → OxigenSystem

Set the initial configuration of the Oxigen system.

Parameters:

  • max_speed (int) – A decimal integer between 0 and 255

  • pit_lane_trigger (PitLaneTrigger) – enum defining if the entering or leaving the pitlane triggers also lane count

  • pit_lane_count (PitLaneCount) – enum defining if the pitlane triggers also lane count

  • power_mean_value (int) – enum defining if the average trigger position or the transferred PWM value is reported for fuel consumptio

Returns:

class descriptor of the system in use

Return type:

OxigenSystem

it returns a OxigenSystem class:

class oxigenlib.OxigenSystem(*, race_state: O2RaceStatus, config: O2Config)

Class representing an Oxigen system it has 2 attributes:

Parameters:

  • race_state (O2RaceStatus) – class containing the actual race state, refer to the RaceState enum for options

  • config (O2Config) – flag reminder if a car has recently been reset

Race state management

to control the race state (example stopped/paused/running/flagged) the following function comes handy. refer to RaceState enumeration for available options.

oxigenlib.set_race_state(new_state: RaceState, sys: OxigenSystem, timer: RaceTimer) → None

Set the race state.

Parameters:

  • new_state (RaceState) – enum defining the desired state to be applied to the race

  • sys (OxigenSystem) – class describing the system configuration

  • timer (RaceTimer) – class providing system timer

Returns:

None

Car controls

The following set of functions enable the configuration of various car parameters during the race.

oxigenlib.set_system_max_speed(max_speed: int, sys: OxigenSystem, timer: RaceTimer) → None

Set the maximum speed allowed. NOTE: this function controls the maximum speed allowed on the track, it overrides every setting applied to singel cars

Parameters:

  • max_speed (int) – A decimal integer between 0 and 255

  • sys (OxigenSystem) – class describing the system configuration

  • timer (RaceTimer) – class providing system timer

Returns:

None

oxigenlib.set_car_max_speed(max_speed: int, car_id: int, sys: OxigenSystem, timer: RaceTimer) → None

Limit the maximum speed of a car.

Parameters:

  • max_speed (int) – A decimal integer between 0 and 255

  • car_id (int) – Number of the car to which the limitation applies, if 0 applies to all cars

  • sys (OxigenSystem) – class describing the system configuration

  • timer (RaceTimer) – class providing system timer

Returns:

None

oxigenlib.set_car_min_speed(min_speed: int, car_id: int, sys: OxigenSystem, timer: RaceTimer) → None

Limit the minimum speed of a car.

Parameters:

  • min_speed (int) – A decimal integer between 0 and 255

  • car_id (int) – Number of the car to which the limitation applies, if 0 applies to all cars

  • sys (OxigenSystem) – class describing the system configuration

  • timer (RaceTimer) – class providing system timer

Returns:

None

oxigenlib.set_pit_stop_speed_limit(pit_speed: int, car_id: int, sys: OxigenSystem, timer: RaceTimer) → None

Limit the maximum speed in pit lanes.

Parameters:

  • pit_speed (int) – A decimal integer between 0 and 255

  • car_id (int) – Number of the car to which the limitation applies, if 0 applies to all cars

  • sys (OxigenSystem) – class describing the system configuration

  • timer (RaceTimer) – class providing system timer

Returns:

None

oxigenlib.set_car_max_brake(max_brake: int, car_id: int, sys: OxigenSystem, timer: RaceTimer) → None

Limit the brake force of a car.

Parameters:

  • max_brake (int) – A decimal integer between 0 and 255

  • car_id (int) – Number of the car to which the limitation applies, if 0 applies to all cars

  • sys (OxigenSystem) – class describing the system configuration

  • timer (RaceTimer) – class providing system timer

Returns:

None

Player

An additional function is available to get all details available for a specific id:

oxigenlib.get_player_data(car_id: int) → CarController | None

Retrieve all data available for a plyer/car.

Parameters:

car_id (int) – Number of the car to which the limitation applies

Returns:

None if no data is available or a CarController instance

If available the retrieved data is a CarController class:

class oxigenlib.carcontroller.CarController(*, car_reset: bool, car_controller_link: bool, car_in_pit_lane: bool, id: ~typing.Annotated[int, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=20)] = <factory>, last_lap_time_s: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)] = <factory>, lap_count: ~typing.Annotated[int, ~annotated_types.Ge(ge=0)] = <factory>, power_mean_value: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)] = <factory>, car_on_track: bool, car_firmware: str, controller_firmware: str, controller_batt_low: bool, track_call_check: bool, lap_time_info: bool, arrow_up_btn: bool, arrow_down_btn: bool, round_btn: bool, timestamp_msg_cs: ~typing.Annotated[int, ~annotated_types.Ge(ge=0)] = <factory>)

Container class for the data package returned by the dongle that represents car-controller pair

Parameters:

  • car_reset (bool) – flag reminder if a car has recently been reset

  • car_controller_link (bool) – link to car available

  • car_in_pit_lane (bool) – flag if car is in the pitlane

  • id (int) – identification number of the car

  • last_lap_time_s (float) – keep the last lap time in seconds

  • lap_count (int) – numbers of laps recorded by the car

  • power_mean_value (float) – position of trigger or average value of pwm signal. It depends on the configuration parameter of the system

  • car_on_track (bool) – flag reporting if the car is or not on the track

  • car_firmware (str) – firmware value of car chip

  • controller_firmware (str) – firmware value of the controller

  • controller_batt_low (bool) – flag reporting low battery status

  • track_call_check (bool) – flag reporting if controller reported track call

  • lap_time_info (bool) – flag reporting if lap time includes a ‘short lap’

  • arrow_up_btn (bool) – up button pressed on controller

  • arrow_down_btn (bool) – down button pressed on controller

  • round_btn (bool) – up button pressed on controller

  • timestamp_msg_cs (int) – timestamp of the transmitted message in centiseconds. Value already aligned with the dongle timer according formula _race timer (last lap)_ of the official oxigen documentation

Timer

Oxigen requires an external timebase, which has to be passed. The library offers a simple timer implementation, but it may be easily replace by a self made implementation.

class oxigenlib.racetimer.RaceTimer

Simple timer to control oxigen protocol base time reference. It can be substituted by another timer as long as it offers the same functions.

pause() → None

pause counting time, but does not reset the timer value

resume() → None

restart counting time, but does not reset the timer value

start() → None

start counting time

stop() → None

stops the timer, but cannot be restartet, by new start the counter restart from zero

value() → int

return timer counter in system timebase [ns]

value_cs() → int

return timer counter in centiseconds [cs] timebase -> used by oxigen

value_cs_bytes() → list[int]

return the timer counter in [cs] base as a 4 bytes list, used for the transmission to the dongle

Important constants

The following preset enumeration allow for a fast selection of important parameters:

class oxigenlib.RaceState(*values)
FLAGGED_LC_OFF = 21
FLAGGED_LC_ON = 5
PAUSED = 4
RUNNING = 3
STOPPED = 1
class oxigenlib.Command(*values)
NO_ACTION = 0
SET_MAX_BRAKE = 5
SET_MAX_SPEED = 2
SET_MIN_LAP_TME = 7
SET_MIN_SPEED = 3
SET_PIT_LANE_SPEED = 1
SET_RF_TX_LEV = 4
class oxigenlib.PitLaneTrigger(*values)
ENTER = 0
LEAVE = 32
class oxigenlib.PitLaneCount(*values)
NO = 64
YES = 0
class oxigenlib.PowerMeanValue(*values)
PWM = 128
TRIGGER = 0