Controllers

Contains the abstract interface for sending commands back to a vehicle interface.

class openxc.controllers.base.CommandResponseReceiver(queue, request, quit_after_first=True)

A receiver that matches the ‘command’ field in responses to the original request.

Construct a new ResponseReceiver.

queue - A multithreading queue that this receiver will pull potential responses from. request - The request we are trying to match up with a response.

class openxc.controllers.base.Controller

A Controller is a physical vehicle interface that accepts commands to be send back to the vehicle. This class is abstract, and implementations of the interface must define at least the write_bytes method.

complex_request(request, wait_for_first_response=True)

Send a compound command request to the interface over the normal data channel.

request - A dict storing the request to send to the VI. It will be
serialized to the currently selected output format.
wait_for_first_response - If true, this function will block waiting for
a response from the VI and return it to the caller. Otherwise, it will send the command and return immediately and any response will be lost.
create_diagnostic_request(message_id, mode, bus=None, pid=None, frequency=None, payload=None, wait_for_ack=True, wait_for_first_response=False, decoded_type=None)

Send a new diagnostic message request to the VI

Required:

message_id - The message ID (arbitration ID) for the request. mode - the diagnostic mode (or service).

Optional:

bus - The address of the CAN bus controller to send the request, either
1 or 2 for current VI hardware.
pid - The parameter ID, or PID, for the request (e.g. for a mode 1
request).
frequency - The frequency in hertz to add this as a recurring diagnostic
requests. Must be greater than 0, or None if it is a one-time request.
payload - A bytearray to send as the request’s optional payload. Only
single frame diagnostic requests are supported by the VI firmware in the current version, so the payload has a maximum length of 6.

wait_for_ack - If True, will wait for an ACK of the command message. wait_for_first_response - If True, this function will block waiting for

a diagnostic response to be received for the request. It will return either after timing out or after 1 matching response is received - there may be more responses to functional broadcast requests that arrive after returning.
Returns a tuple of
([list of ACK responses to create request],
[list of diagnostic responses received])
delete_diagnostic_request(message_id, mode, bus=None, pid=None)
device_id()

Request the unique device ID of the attached VI.

modem_configuration(host, port)

Set the host:port for the Cellular device to send data to.

Returns True if the command was successful.

rtc_configuration(unix_time)

Set the Unix time if RTC is supported on the device.

Returns True if the command was successful.

sd_mount_status()

Request for SD Mount status if available.

set_acceptance_filter_bypass(bus, bypass)

Control the status of CAN acceptance filter for a bus.

Returns True if the command was successful.

set_passthrough(bus, enabled)

Control the status of CAN message passthrough for a bus.

Returns True if the command was successful.

set_payload_format(payload_format)

Set the payload format for messages sent to and from the VI.

Returns True if the command was successful.

set_predefined_obd2_requests(enabled)

Control if pre-defined OBD2 requests should be sent.

Returns True if the command was successful.

stop()
version()

Request a firmware version identifier from the VI.

write(**kwargs)

Serialize a raw or translated write request and send it to the VI, following the OpenXC message format.

write_bytes(data)

Write the bytes in data to the controller interface.

write_raw(message_id, data, bus=None, frame_format=None)

Send a raw write request to the VI.

write_translated(name, value, event=None)

Send a translated write request to the VI.

exception openxc.controllers.base.ControllerError
class openxc.controllers.base.DiagnosticResponseReceiver(queue, request)

A receiver that matches the bus, ID, mode and PID from a diagnostic request to an incoming response.

class openxc.controllers.base.ResponseReceiver(queue, request, quit_after_first=True)

All commands to a vehicle interface are asynchronous. This class is used to wait for the response for a particular request in a thread. Before making a request, a ResponseReceiver is created to wait for the response. All responses received from the VI (which may or may not be in response to this particular command) are passed to the ResponseReceiver, until it either times out waiting or finds a matching response.

The synchronization mechanism is a multiprocessing Queue. The ResponseReceiver blocks waiting on a new response to be added to the queue, and the vehicle interface class puts newly received responses in the queues of ResponseReceivers as they arrive.

Construct a new ResponseReceiver.

queue - A multithreading queue that this receiver will pull potential responses from. request - The request we are trying to match up with a response.

COMMAND_RESPONSE_TIMEOUT_S = 0.5
handle_responses()

Block and wait for responses to this object’s original request, or until a timeout (self.COMMAND_RESPONSE_TIMEOUT_S).

This function is handy to use as the target function for a thread.

The responses received (or None if none was received before the timeout) is stored in a list at self.responses.

start()
wait_for_responses()

Block the thread and wait for the response to the given request to arrive from the VI. If no matching response is received in COMMAND_RESPONSE_TIMEOUT_S seconds, returns anyway.

Controller implementation for a virtual serial device.

class openxc.controllers.serial.SerialControllerMixin

An implementation of a Controller type that connects to a virtual serial device.

This class acts as a mixin, and expects self.device to be an instance of serial.Serial.

TODO Bah, this is kind of weird. refactor the relationship between sources/controllers.

WAITIED_FOR_CONNECTION = False
complex_request(request, blocking=True)

Send a compound command request to the interface over the normal data channel.

request - A dict storing the request to send to the VI. It will be
serialized to the currently selected output format.
wait_for_first_response - If true, this function will block waiting for
a response from the VI and return it to the caller. Otherwise, it will send the command and return immediately and any response will be lost.
write_bytes(data)

Write the bytes in data to the controller interface.

Controller implementation for an OpenXC USB device.

class openxc.controllers.usb.UsbControllerMixin

An implementation of a Controller type that connects to an OpenXC USB device.

This class acts as a mixin, and expects self.device to be an instance of usb.Device.

TODO bah, this is kind of weird. refactor the relationship between sources/controllers.

COMPLEX_CONTROL_COMMAND = 131
out_endpoint

Open a reference to the USB device’s only OUT endpoint. This method assumes that the USB device configuration has already been set.

write_bytes(data)

Write the bytes in data to the controller interface.