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.
- types (int) – Filter the results to given types of devices. The
NEODEVICE_* constants defined in
-
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 theNeoDevice.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 theNeoDevice.get_messages()
method.Raises: OpenFailedError – If the device cannot be opened.
-
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.- network_id (int) – The network to transmit on. See NETID_* in
-
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.
- callback (func) – The method or function to be called. This must
take two parameters: 1) a message as a
-
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 asstructures.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 asstructures.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).
- device (structures.NeoDevice) – Device identifier, as returned by
-
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)¶