# Python API

The simplyCAN API provides a simple programming interface for the development of CAN applications on Windows PCs and on Linux PCs.

    dSimplyReturnValues = {
        0:    "No error occurred",
        -1:   "Unable to open the serial port",
        -2:   "Access on serial port denied",
        -3:   "Serial communication port is closed",
        -4:   "Serial communication error",
        -5:   "Command unknown on device",
        -6:   "Command response timeout reached",
        -7:   "Unexpected command response received",
        -8:   "Command response error",
        -9:   "Invalid simplyCAN protocol version",
        -10:  "Invalid device firmware version",
        -11:  "Invalid simplyCAN product string",
        -12:  "Invalid CAN state",
        -13:  "Invalid CAN baud-rate",
        -14:  "Message could not be sent. TX is busy",
        -15:  "API is busy",
        -100: "Invalid DLL/SO version number",
    }

## Class Message

CAN messages used for reception and transmission.

    class Message(object)

### __init__()

Initialization of the CAN message class.

    def __init__(self, ident, payload=[], flags=[], timestamp=0)

Parameter:

- `ident` - 11 or 29 bit CAN message identifier

- `payload` - CAN message payload

- `flags` - ‘E’ for extended frame, ‘R’ for remote frame

### __str__()

Format the CAN message as string for output.

    def __str__(self)

Return value:

Returns the CAN message as formated string.

## Class Identification

Device identification message.

    class Identification(object)

### __init__()

Initialization of the device identification message class.

    def __init__(self)

### __str__()

Format the Device identification message as string for output.

    def __str__(self)

Return value:

Returns the device identification message as formated string.

## Functions

### retrieve_serial_port()

Retrieve the first serial port with a connected simplyCAN device.

    def retrieve_serial_port()

Return value:

Port info as string, like ‘COM3’ for Windows or ‘ttyACM0’ for Linux or None if not available.

### open()

Opens the serial communication interface. The message filter of the CAN controller is opened for all message identifiers.

    def open(serial_port)

Parameter:

- `serial_port` - Name of the serial communication port (e.g. COM1 or /dev/ttyACM0). Use the simplyCAN bus monitor to detect on which serial COM port the simplyCAN is connected. With Windows it is also possible to use the device manager and with Linux the command “ls -l /dev/serial/by-id”.

Return value:

Return True if the function succeeded and False if an error occurred. Call get_last_error for more information.

### close()

Closes the serial communication interface and resets the CAN controller.

    def close()

Return value:

Return True if the function succeeded and False if an error occurred. Call get_last_error for more information.

### initialize_can()

Initializes the CAN controller.

    def initialize_can(bitrate)

Parameter:

- `bitrate` - CAN bitrate as integer value, possible values: 10, 20, 50, 125, 250, 500, 800, 1000

Return value:

Return True if the function succeeded and False if an error occurred. Call get_last_error for more information.

### identify()

Gets firmware and hardware information about the simplyCAN device.

    def identify()

Return value:

Return the firmware and hardware information as a struct Identification or None if an error occurred. Call get_last_error for more information.

### start_can()

Starts the CAN controller. Sets the CAN controller into running mode and clears the CAN message FIFOs. In running mode CAN messages can be transmitted and received.

    def start_can()

Return value:

Return True if the function succeeded and False if an error occurred. Call get_last_error for more information.

### stop_can()

Stops the CAN controller. Sets the CAN controller into init mode. Does not reset the message filter of the CAN controller. Only stop the CAN controller when the CAN_STATUS_PENDING flag is not set.

    def stop_can()

Return value:

Return True if the function succeeded and False if an error occurred. Call get_last_error for more information.

### reset_can()

Resets the CAN controller (hardware reset) and clears the message filter (open for all message identifiers). Sets the CAN controller into init mode.

    def reset_can()

Return value:

Return True if the function succeeded and False if an error occurred. Call get_last_error for more information.

### can_status()

Gets the status of the CAN controller.

    def can_status()

Return value:

Return a pair (can_sts, tx_free) where can_sts is the CAN status as bit coded 16 bit value, and tx_free the number of free elements in the CAN message tx FIFO. If an error occurred the return value is (None, None). Call get_last_error for more information.

### set_filter()

Sets the 11 or 29 bit message filter of the CAN controller. To set the 29 bit message filter, the MSB in parameter value must be set.

    def set_filter(mask, value)

Parameter:

- `mask` - 11 or 29 bit CAN message identifier mask.

- `value` - 11 or 29 bit CAN message identifier value, set MSB to set the 29 bit message filter.

Return value:

Return True if the function succeeded and False if an error occurred. Call get_last_error for more information.

### receive()

Receives a single CAN message.

    def receive()

Return value:

Return a pair (res, can_msg) where res is the result code, and can_msg the received CAN message. If no message is available in the receive queue the result code is 0 and can_msg None. If a message is available the result code is 1 and the can_msg is returned as a struct Message. If an error occurred the result code is -1 and the can_msg None. Call get_last_error for more information.

### send()

Writes a CAN message to the transmit FIFO. To check if the message is transmitted, request the CAN status with can_status.

    def send(msg)

Parameter:

- `msg` - CAN message

Return value:

Return True if the function succeeded and False if an error occurred. Call get_last_error for more information.

### flush_tx_fifo()

Flush the tx fifo to speed up the transmission of cached CAN messages.

    def flush_tx_fifo()

Return value:

Return True if the function succeeded and False if an error occurred. Call get_last_error for more information.

### get_last_error()

Gets the last error code (see dSimplyReturnValues). After reading the error code with get_last_error the error code is set to 0. Each error can only be read once.

    def get_last_error()

### get_error_string()

Gets the error string to a related error code

    def get_error_string(err_code)