neovi.neodevice module

This module provides classes representing neoVI devices, all derived from core functionality in the NeoDevice class. These classes form a layer of abstraction on top of the wrapper functions for the ICS DLL API defined in neovi.

The following neoVI classes are defined:

Below is a simple example that logs all messages to and from a specified ECU.

import time
import logging
import neovi.neodevice as neodevice
import neovi.neovi as neovi
from neovi.structures import format_array, get_status_bits_set


TARGET_ECU = 0x456


def log_messages(result, msgs, errors):
    # result is -1 on success, the value returned by icsneoGetLastAPIError otherwise.
    # (See http://www.intrepidcs.com/support/ICSDocumentation/neoVIDLL/apiErrorMessages.htm)
    # msgs is an array of icsSpyMessage.
    # (See structures.py)
    # errors is an array of c_int.
    # (See link as per meaning of "result")
    for msg in msgs:
        if msg.ArbIDOrHeader in [TARGET_ECU, TARGET_ECU + 8]:
            logging.debug('ArbIDOrHeader = %X, number data bytes = %X' % (msg.ArbIDOrHeader, msg.NumberBytesData))
            logging.debug('Data = %s' % format_array(msg.Data))
            logging.debug('Ack = %s' % format_array(msg.AckBytes))
            logging.debug('Value = %f, misc data = %X' % (msg.Value, msg.MiscData))
            stat, stat2 = get_status_bits_set(msg)
            stat = stat + stat2
            for i in range(0, len(stat), 3):
                stats = stat[i:i+3]
                logging.debug('%s' % ', '.join(stats))
            logging.debug('')


# The below assumes the first device is the one you want, which will be true
# if there's only one attached.
neodevice.init_api()
dev = neodevice.find_devices(neovi.NEODEVICE_FIRE)[0]
dev.open()

dev.subscribe_to_all(log_messages)

# Quick hack to wait until the user hits Ctrl+C
try:
    while 1:
        time.sleep(1)
except KeyboardInterrupt:
    pass

dev.close()

init_api()

Load the neoVI API library and initialise it. This must be called before making any API calls.

find_devices(types=neovi.NEODEVICE_ALL, auto_open=False)

Find any attached neoVI devices.

Parameters:

• types (int) – Filter the results to given types of devices. The NEODEVICE_* constants defined in neovi can be OR’d together.
• auto_open (bool) – Determines whether the discovered devices should be automatically opened. If this is False then you must call NeoDevice.open() on any devices that are to be used.

exception OpenFailedError

Failed to open a NeoVI device.

exception InvalidConfigurationError

An invalid configuration was supplied to be written to the device.

class NeoDevice(device, auto_open=False, launch_msg_queue_thread=True)

Represents a generic neoVI device, providing an interface for transmitting and receiving messages as well as configuring the device.

Typically these objects would be created via a call to find_devices(), which returns a list of pre-constructed NeoDevice objects.

Parameters:

• device (structures.NeoDevice) – Device identifier, as returned by neovi.FindNeoDevices().
• auto_open (bool) – Determines whether the device should be automatically opened. If this is False then you must call NeoDevice.open() in order to open the device.
• launch_msg_queue_thread (bool) – Determines whether to start a thread to receive incoming messages. If this is False then you must process the message queue via the NeoDevice._process_msg_queue() method or fetch the messages via the NeoDevice.get_messages() method. Only applicable if auto_open = True.

open(launch_msg_queue_thread=True)

Open the device and optionally launch the message thread. This is only required if the object was constructed with auto_open = False.

Parameters:launch_msg_queue_thread (bool) – Determines whether to start a thread to receive incoming messages. If this is False then you must process the message queue via the NeoDevice._process_msg_queue() method or fetch the messages via the NeoDevice.get_messages() method. Raises:OpenFailedError – If the device cannot be opened.

get_type()

Returns:The type of device represented. See NEODEVICE_* in neovi.

get_settings()

Get the current device configuration.

Returns:A 2-tuple of i) either SUCCESS or an error code (see Error Messages in the ICS API documentation) and ii) a device-specific configuration object.

set_settings(settings, save_to_eeprom=False)

Set the device configuration.

Parameters:

• settings – A device-specific configuration.
• save_to_eeprom (bool) – Determines if the configuration will be persisted across device power cycles.

Returns:

Either SUCCESS or an error code (see Error Messages in the ICS API documentation).

tx_raw_message(msg, network_id)

Transmits a pre-constructed message.

Parameters:

• msg (icsSpyMessage) – The message to transmit.
• network_id (int) – The network to transmit on. See NETID_* in neovi.

Returns:

Status code. neovi.SUCCESS or an error code. See TxMessages in the ICS API documentation for possible codes (constants not yet defined within pyneovi).

tx_message(network_id, dest, msg_type, payload)

Transmits a pre-constructed message.

Parameters:

• network_id (int) – The network to transmit on. See NETID_* in neovi.
• dest (int) – The address of the destination ECU.
• msg_type (int) – The message type to send. See can.
• payload (list of ints) – Up to 6 bytes to send.

Returns:

Tuple of status code and transmission id. Status code is neovi.SUCCESS or an error code. See TxMessages in the ICS API documentation for possible codes (constants not yet defined within pyneovi). Transmission id can be safely ignored.

subscribe_to(callback, network=None, address=None, msg_type=None, additional_bytes=None, auto_remove=False, user_data=None)

Set a callback function to be called upon reception of a defined subset of messages. Note that this will only occur if the message thread has been started or if NeoDevice._process_msg_queue() is called manually. All parameters other than callback, auto_remove, and user_data define filtering criteria that will be used to determine whether to pass the message to this callback.

Parameters:

• callback (func) – The method or function to be called. This must take two parameters: 1) a message as a structures.icsSpyMessage object, and 2) a user data parameter with no pre-defined meaning within pyneovi.
• network (int) – The network ID of interest (see NETID_* in neovi). If None (the default) then it will be ignored for filtering.
• address (int) – The address of the ECU of interest. If None (the default) then it will be ignored for filtering.
• msg_type (int) – The message type of interest (see can). If None (the default) then it will be ignored for filtering.
• additional_bytes (list of ints) – Additional payload bytes to use for filtering. May be an empty list. A value of None (the default) will be converted to an empty list automatically.
• auto_remove (bool) – If True then the subscription is removed once the first message matching the provided criteria has been received.
• user_data – This parameter has no pre-defined meaning within pyneovi - the value is passed to the callback function along with the received message.

subscribe_to_all(callback)

Set a callback function to be called upon reception of any message. Note that this will only occur if the message thread has been started or if NeoDevice._process_msg_queue() is called manually.

Parameters:callback (func) –

The method or function to be called. This must take three parameters: 1) a statue code of either neovi.SUCCESS or an error code (see TxMessages in the ICS API documentation for possible codes (constants not yet defined within pyneovi)), 2) a list of messages as structures.icsSpyMessage objects, and 3) a list of errors as integers (see Error Messages in the ICS API documentation for a complete error list).

get_messages()

Fetch pending received messages. Note that if the message thread was launched then this should not be called.

Returns:A tuple containing 1) a statue code of either neovi.SUCCESS or an error code (see TxMessages in the ICS API documentation for possible codes (constants not yet defined within pyneovi)), 2) a list of messages as structures.icsSpyMessage objects, and 3) a list of errors as integers (see Error Messages in the ICS API documentation for a complete error list).

setup_networks(network_settings)

get_firmware_version()

Return the firmware version of the device.

Returns:A firmware info object if the call succeeded, otherwise None. Return type:structures.APIFirmwareInfo

get_dll_firmware_version()

Return the firmware version stored within the DLL API.

Returns:A firmware info object if the call succeeded, otherwise None. Return type:structures.APIFirmwareInfo

force_firmware_update()

Force the firmware on the device to be updated to the version stored in the DLL API.

close()

Close the device and shutdown the message thread (if there is one).

class NeoFire(device, auto_open=True, launch_msg_queue_thread=True)

Represents a neoVI Fire device. Should be used if settings specific to the neoVI Fire must be read/written.

Base class: NeoDevice

get_settings()

Get the current device configuration.

Returns:A 2-tuple of i) either SUCCESS or an error code (see Error Messages in the ICS API documentation) and ii) a structures.SFireSettings object.

set_settings(settings, save_to_eeprom=False)

Set the device configuration.

Parameters:

• settings (structures.SFireSettings) – The new configuration.
• save_to_eeprom (bool) – Determines if the configuration will be persisted across device power cycles.

Returns:

Either SUCCESS or an error code (see Error Messages in the ICS API documentation).

class NeoRed(device, auto_open=True, launch_msg_queue_thread=True)

Represents a neoVI Red device. Should be used if settings specific to the neoVI Red must be read/written.

Base class: NeoFire

class NeoVCAN3(device, auto_open=True, launch_msg_queue_thread=True)

Represents a ValueCAN3 device. Should be used if settings specific to the ValueCAN3 must be read/written.

Base class: NeoDevice

get_settings()

Get the current device configuration.

Returns:A 2-tuple of i) either SUCCESS or an error code (see Error Messages in the ICS API documentation) and ii) a structures.SVCAN3Settings object.

set_settings(settings, save_to_eeprom=False)

Set the device configuration.

Parameters:

• settings (structures.SVCAN3Settings) – The new configuration.
• save_to_eeprom (bool) – Determines if the configuration will be persisted across device power cycles.

Returns:

Either SUCCESS or an error code (see Error Messages in the ICS API documentation).

class NeoBlue(device, auto_open=True, launch_msg_queue_thread=True)

Represents a neoVI Blue device. Should be used if settings specific to the neoVI Blue must be read/written.

Base class: NeoDevice

set_settings(settings, save_to_eeprom=False)

Set the device configuration.

Parameters:

• settings – An array of configuration bytes (see Configuration Array in the ICS API documentation).
• save_to_eeprom (bool) – Determines if the configuration will be persisted across device power cycles.

Returns:

Either SUCCESS or an error code (see Error Messages in the ICS API documentation).

Raises:

InvalidConfigurationError – If the size of the settings array is incorrect.

class NeoDWVCAN(device, auto_open=True, launch_msg_queue_thread=True)