Welcome to libicsneo’s documentation!¶

API Usage¶

API Concepts¶

Overview¶

Events convey information about the API’s inner workings to the user. There are 3 severity levels: EventInfo, EventWarning, and Error. However, the API treats events of severities EventInfo and EventWarning differently than those of severity Error . From here on out, when we (and the API functions) refer to “events”, we refer exclusively to those of severities EventInfo and EventWarning, which use the events system. Those of severity Error are referred to as “errors”, which use a separate errors system.

Events should periodically be read out in order to avoid overflowing, and the last error should be read out immediately after an API function fails.

Additionally, event callbacks can be registered, which may remove the need to periodically read events in some cases.

Events¶

The API stores events in a single buffer that can has a default size of 10,000 events. This limit includes 1 reserved slot at the end of the buffer for a potential Event of type TooManyEvents and severity EventWarning, which is added when there are too many events for the buffer to hold. This could occur if the events aren’t read out by the user often enough, or if the user sets the size of the buffer to a value smaller than the number of existing events. There will only ever be one of these TooManyEvents events, and it will always be located at the very end of the buffer if it exists. Because of this reserved slot, the buffer by default is able to hold 9,999 events. If capacity is exceeded, the oldest events in the buffer are automatically discarded until the buffer is exactly at capacity again. When events are read out by the user, they are removed from the buffer. If an event filter is used, only the filtered events will be removed from the buffer.

In a multithreaded environment, all threads will log their events to the same buffer. In this case, the order of events will largely be meaningless, although the behavior of TooManyEvents is still guaranteed to be as described above.

Event Callbacks¶

Users may register event callbacks, which are automatically called whenever a matching event is logged. Message callbacks consist of a user-defined std::function< void( std::shared_ptr<APIEvent> ) > and optional EventFilter used for matching. If no EventFilter is provided, the default-constructed one will be used, which matches any event. Registering a callback returns an int representing the id of the callback, which should be stored by the user and later used to remove the callback when desired. Note that this functionality is only available in C and C++. C does not currently support filters.

Event callbacks are run after the event has been added to the buffer of events. The buffer of events may be safely modified within the callback, such as getting (flushing) the type and severity of the triggering event. Using event callbacks in this manner means that periodically reading events is unnecessary.

Errors¶

The error system is threadsafe and separate from the events system. Each thread keeps track of the last error logged on it, and getting the last error will return the last error from the calling thread, removing it in the process. Trying to get the last error when there is none will return an event of type NoErrorFound and severity EventInfo.

The API also contains some threads for internal use which may potentially log errors of their own and are inaccessible to the user. These threads have been marked to downgrade any errors that occur on them to severity EventWarning and will log the corresponding event in the events system described above.

Device Concepts¶

Open/Close Status¶

In order to access device functionality, the device must first be opened, which begins communication between the API and the device. The exception to this is setting the message polling status of the device. Trying to open/close the device when the device is already open/closed will result in an error being logged on the calling thread.

Online/Offline Status¶

Going online begins communication between the device and the rest of the network. In order to be online, the device must also be open. Trying to go online/offline when the device is already online/offline will result in an error being logged on the calling thread.

It is possible to have a device be both open and offline. In this situation, device settings such as the baudrate may still be read and changed. This is useful for setting up your device properly before going online and joining the network.

Message Callbacks and Polling¶

In order to handle messages, users may register message callbacks, which are automatically called whenever a matching message is received. Message callbacks consist of a user-defined std::function< void( std::shared_ptr<Message> ) > and optional message filter used for matching. If no message filter is provided, the default-constructed one will be used, which matches any message. Registering a callback returns an int representing the id of the callback, which should be stored by the user and later used to remove the callback when desired. Note that this functionality is only available in C and C++. C does not currently support filters.

The default method of handling messages is to enable message polling, which is built upon message callbacks. Enabling message polling will register a callback that stores each received message in a buffer for later retrieval. The default limit of this buffer is 20,000 messages. If the limit is exceeded, the oldest messages will be dropped until the buffer is at capacity, and an error will be logged on the calling thread. To avoid exceeding the limit, try to get messages periodically, which will flush the buffer upon each call. Attempting to read messages without first enabling message polling will result in an error being logged on the calling thread.

It is recommended to either enable message polling or manually register callbacks to handle messages, but not both.

Write Blocking Status¶

The write blocking status of the device determines the behavior of attempting to transmit to the device (likely via sending messages) with a large backlog of messages. If write blocking is enabled, then the transmitting thread will wait for the entire buffer to be transmitted. If write blocking is disabled, then the attempt to transmit will simply fail and an error will be logged on the calling thread.

C++ API (icsneocpp)¶

Reference¶

namespace icsneo¶

Typedefs

typedef std::function<void(APIEvent::Type, APIEvent::Severity)> device_eventhandler_t¶

Functions

std::vector<std::shared_ptr<Device>> FindAllDevices()¶

std::vector<DeviceType> GetSupportedDevices()¶

size_t EventCount(EventFilter filter = EventFilter())¶

std::vector<APIEvent> GetEvents(EventFilter filter, size_t max = 0)¶

std::vector<APIEvent> GetEvents(size_t max = 0, EventFilter filter = EventFilter())¶

void GetEvents(std::vector<APIEvent> &events, EventFilter filter, size_t max = 0)¶

void GetEvents(std::vector<APIEvent> &events, size_t max = 0, EventFilter filter = EventFilter())¶

APIEvent GetLastError()¶

void DiscardEvents(EventFilter filter = EventFilter())¶

void SetEventLimit(size_t newLimit)¶

size_t GetEventLimit()¶

class Main51Message : public icsneo::Message ¶: #include <main51message.h>
Subclassed by icsneo::SerialNumberMessage

class Message¶: #include <message.h>
Subclassed by icsneo::CANMessage, icsneo::EthernetMessage, icsneo::Main51Message, icsneo::ReadSettingsMessage, icsneo::ResetStatusMessage

class MessageCallback¶: #include <messagecallback.h>
Subclassed by icsneo::CANMessageCallback, icsneo::Main51MessageCallback

class MessageFilter¶: #include <messagefilter.h>
Subclassed by icsneo::CANMessageFilter, icsneo::Main51MessageFilter

class Device¶

Public Functions

virtual ~Device()¶

uint16_t getTimestampResolution() const¶

DeviceType getType() const¶

uint16_t getProductId() const¶

std::string getSerial() const¶

uint32_t getSerialNumber() const¶

const neodevice_t &getNeoDevice() const¶

std::string describe() const¶

virtual bool open()¶

virtual bool close()¶

virtual bool isOnline() const¶

virtual bool isOpen() const¶

virtual bool goOnline()¶

virtual bool goOffline()¶

bool enableMessagePolling()¶

bool disableMessagePolling()¶

bool isMessagePollingEnabled()¶

std::pair<std::vector<std::shared_ptr<Message>>, bool> getMessages()¶

bool getMessages(std::vector<std::shared_ptr<Message>> &container, size_t limit = 0, std::chrono::milliseconds timeout = std::chrono::milliseconds(0))¶

size_t getCurrentMessageCount()¶

size_t getPollingMessageLimit()¶

void setPollingMessageLimit(size_t newSize)¶

int addMessageCallback(const MessageCallback &cb)¶

bool removeMessageCallback(int id)¶

bool transmit(std::shared_ptr<Message> message)¶

bool transmit(std::vector<std::shared_ptr<Message>> messages)¶

void setWriteBlocks(bool blocks)¶

const std::vector<Network> &getSupportedRXNetworks() const¶

const std::vector<Network> &getSupportedTXNetworks() const¶

virtual bool isSupportedRXNetwork(const Network &net) const¶

virtual bool isSupportedTXNetwork(const Network &net) const¶

virtual size_t getNetworkCountByType(Network::Type) const¶

virtual Network getNetworkByNumber(Network::Type, size_t) const¶

virtual std::vector<std::shared_ptr<FlexRay::Controller>> getFlexRayControllers() const¶

const device_eventhandler_t &getEventHandler() const¶

Public Members

std::shared_ptr<Communication> com¶

std::unique_ptr<IDeviceSettings> settings¶

Public Static Functions

static std::string SerialNumToString(uint32_t serial)¶

static uint32_t SerialStringToNum(const std::string &serial)¶

static bool SerialStringIsNumeric(const std::string &serial)¶

Friends

std::ostream &operator<<(std::ostream &os, const Device &device)¶

C API (icsneoc)¶

Reference¶

Typedefs¶

typedef void *devicehandle_t¶

typedef int32_t neodevice_handle_t¶

typedef uint32_t devicetype_t¶

Structures¶

struct neoversion_t¶

Public Members

uint16_t major¶

uint16_t minor¶

uint16_t patch¶

const char *metadata¶

const char *buildBranch¶

const char *buildTag¶

char reserved[32]¶

struct neodevice_t¶

Public Members

devicehandle_t device¶

neodevice_handle_t handle¶

devicetype_t type¶

char serial[7]¶

struct neomessage_t¶

Public Members

neomessage_statusbitfield_t status¶

uint64_t timestamp¶

uint64_t timestampReserved¶

const uint8_t *data¶

size_t length¶

uint8_t header[4]¶

uint16_t netid¶

uint8_t type¶

uint8_t reserved[17]¶

struct neomessage_can_t¶

Public Members

neomessage_statusbitfield_t status¶

uint64_t timestamp¶

uint64_t timestampReserved¶

const uint8_t *data¶

size_t length¶

uint32_t arbid¶

uint16_t netid¶

uint8_t type¶

uint8_t dlcOnWire¶

uint8_t reserved[16]¶

Functions¶

Functions

void icsneo_findAllDevices(neodevice_t *devices, size_t *count)¶

Find Intrepid hardware connected via USB and Ethernet.

For each found device, a

neodevice_t structure will be written into the memory you provide.

Parameters

devices: Pointer to memory where devices should be written. If NULL, the current number of detected devices is written to count.
count: Pointer to a size_t, which should initially contain the number of devices the buffer can hold, and will afterwards contain the number of devices found.

The neodevice_t can later be passed by reference into the API to perform actions relating to the device. The neodevice_t contains a handle to the internal memory for the icsneo::Device object. The memory for the internal icsneo::Device object is managed by the API.

Any neodevice_t objects which have not been opened will become invalid when icsneo_findAllDevices() is called again. To invoke this behavior without finding devices again, call icsneo_freeUnconnectedDevices().

If the size provided is not large enough, the output will be truncated. An icsneo::APIEvent::OutputTruncatedError will be available in icsneo_getLastError() in this case.

void icsneo_freeUnconnectedDevices()¶

Invalidate neodevice_t objects which have not been opened.

See icsneo_findAllDevices() for information regarding the neodevice_t validity contract.

bool icsneo_serialNumToString(uint32_t num, char *str, size_t *count)¶

Convert a serial number in numerical format to its string representation.

On older devices, the serial number is one like 138635, the numerical representation is the same as the string representation.

Return

True if str contains the string representation of the given serial number.

Parameters

num: A numerical serial number.
str: A pointer to a buffer where the string representation will be written. NULL can be passed, which will write a character count to count.
count: A pointer to a size_t which, prior to the call, holds the maximum number of characters to be written (so str must be of size count + 1 to account for the NULL terminator), and after the call holds the number of characters written.

On newer devices, the serial number is one like RS2259, and this function can convert the numerical value back into the string seen on the back of the device.

A query for length (str == NULL) will return false. icsneo_getLastError() should be checked to verify that the neodevice_t provided was valid.

The client application should provide a buffer of size 7, as serial numbers are always 6 characters or fewer.

If the size provided is not large enough, the output will be NOT be truncated. Nothing will be written to the output. Instead, an icsneo::APIEvent::BufferInsufficient will be available in icsneo_getLastError(). False will be returned, and count will now contain the number of bytes necessary to store the full string.

uint32_t icsneo_serialStringToNum(const char *str)¶

Convert a serial number in string format to its numerical representation.

On older devices, the serial number is one like 138635, and this string will simply be returned as a number.

Return

The numerical representation of the serial number, or 0 if the conversion was unsuccessful.

Parameters

str: A NULL terminated string containing the string representation of an Intrepid serial number.

On newer devices, the serial number is one like RS2259, and this function can convert that string to a number.

bool icsneo_isValidNeoDevice(const neodevice_t *device)¶

Verify that a neodevice_t is valid.

This check is automatically performed at the beginning of any API function that operates on a device. If there is a failure, an icsneo::APIEvent::InvalidNeoDevice will be available in

icsneo_getLastError().

Return

True if the neodevice_t is valid.

Parameters

device: A pointer to the neodevice_t structure to operate on.

See icsneo_findAllDevices() for information regarding the neodevice_t validity contract.

bool icsneo_openDevice(const neodevice_t *device)¶

Connect to the specified hardware.

The device

MUST be opened before any other functions which operate on the device will be valid.

Return

True if the connection could be opened.

Parameters

device: A pointer to the neodevice_t structure specifying the device to open.

See icsneo_goOnline() for information about enabling network communication once the device is open.

If the open did not succeed, icsneo_getLastError() should provide more information about why.

If the device was already open, an icsneo::APIEvent::DeviceCurrentlyOpen will be available in icsneo_getLastError().

bool icsneo_closeDevice(const neodevice_t *device)¶

Close an open connection to the specified hardware.

After this function succeeds, the

neodevice_t will be invalid. To connect again, you must call icsneo_findAllDevices() or similar to re-find the device.

Return

True if the connection could be closed.

Parameters

device: A pointer to the neodevice_t structure specifying the device to close.

bool icsneo_isOpen(const neodevice_t *device)¶

Verify network connection for the specified hardware.

This function does not modify the working state of the device at all.

Return

True if the device is connected.

Parameters

device: A pointer to the neodevice_t structure specifying the device to operate on.

See icsneo_openDevice() for an explanation about the concept of being “open”.

bool icsneo_goOnline(const neodevice_t *device)¶

Enable network communication for the specified hardware.

The device is not “online” when it is first opened. It is not possible to receive or transmit while the device is “offline”. Network controllers are disabled. (i.e. In the case of CAN, the hardware will not send ACKs on the client application’s behalf)

Return

True if communication could be enabled.

Parameters

device: A pointer to the neodevice_t structure specifying the device to operate on.

This allows filtering or handlers to be set up before allowing traffic to flow.

This also allows device settings to be set (i.e. baudrates) before enabling the controllers, which prevents momentarily causing loss of communication if the baud rates are not correct.

bool icsneo_goOffline(const neodevice_t *device)¶

Disable network communication for the specified hardware.

See

icsneo_goOnline() for an explanation about the concept of being “online”.

Return

True if communication could be disabled.

Parameters

device: A pointer to the neodevice_t structure specifying the device to operate on.

bool icsneo_isOnline(const neodevice_t *device)¶

Verify network communication for the specified hardware.

This function does not modify the working state of the device at all.

Return

True if communication is enabled.

Parameters

device: A pointer to the neodevice_t structure specifying the device to operate on.

See icsneo_goOnline() for an explanation about the concept of being “online”.

bool icsneo_enableMessagePolling(const neodevice_t *device)¶

Enable buffering of messages for the specified hardware.

By default, traffic the device receives will not reach the client application. The client application must register traffic handlers, enable message polling, or both. This function addresses message polling.

Return

True if polling could be enabled.

Parameters

device: A pointer to the neodevice_t structure specifying the device to operate on.

With polling enabled, all traffic that the device receives will be stored in a buffer managed by the API. The client application should then call icsneo_getMessages() periodically to take ownership of the messages in that buffer.

The API managed buffer will only grow to a specified size, 20k messages by default. See icsneo_getPollingMessageLimit() and icsneo_setPollingMessageLimit() for more information.

In high traffic situations, the default 20k message limit can be reached very quickly. The client application will have to call icsneo_getMessages() very often to avoid losing messages, or change the limit.

If the message limit is exceeded before a call to icsneo_getMessages() takes ownership of the messages, the oldest message will be dropped (LOST) and an icsneo::APIEvent::PollingMessageOverflow will be flagged for the device.

This function will succeed even if the device is not open.

bool icsneo_disableMessagePolling(const neodevice_t *device)¶

Disable buffering of messages for the specified hardware.

See

icsneo_enableMessagePolling() for more information about the message polling system.

Return

True if polling could be disabled.

Parameters

device: A pointer to the neodevice_t structure specifying the device to operate on.

Any messages left in the API managed buffer will be lost upon disabling polling.

bool icsneo_isMessagePollingEnabled(const neodevice_t *device)¶

Verify message polling status for the specified hardware.

This function does not modify the working state of the device at all.

Return

True if polling is enabled.

Parameters

device: A pointer to the neodevice_t structure specifying the device to operate on.

See icsneo_enableMessagePolling() for an explanation about how polling works.

bool icsneo_getMessages(const neodevice_t *device, neomessage_t *messages, size_t *items, uint64_t timeout)¶

Read out messages which have been recieved.

Messages are available using this function if

icsneo_goOnline() and icsneo_enableMessagePolling() have been called. See those functions for more information.

Return

True if the messages were read out successfully (even if there were no messages to read) or if the count was read successfully.

Parameters

device: A pointer to the neodevice_t structure specifying the device to operate on.
messages: A pointer to a buffer which neomessage_t structures will be written to. NULL can be passed, which will write the current message count to size.
items: A pointer to a size_t which, prior to the call, holds the maximum number of messages to be written, and after the call holds the number of messages written.
timeout: The number of milliseconds to wait for a message to arrive. A value of 0 indicates a non-blocking call. Querying for the current message count is always asynchronous and ignores this value.

Messages are read out of the API managed buffer in order of oldest to newest. As they are read out, they are removed from the API managed buffer.

If size is too small to contain all messages, as many messages as will fit will be read out. Subsequent calls to icsneo_getMessages() can retrieve any messages which were not read out.

The memory for the data pointer within the neomessage_t is managed by the API. Do not attempt to free the data pointer. The memory will become invalid the next time icsneo_getMessages() is called for this device.

size_t messageCount;
bool result = icsneo_getMessages(device, NULL, &messageCount, 0); // Reading the message count
// Handle errors here
neomessage_t* messages = malloc(messageCount * sizeof(neomessage_t)); // It is also possible and encouraged to use a static buffer
result = icsneo_getMessages(device, messages, &messageCount, 0); // Non-blocking
// Handle errors here
for(size_t i = 0; i < messageCount; i++) {
    switch(messages[i].type) {
        case ICSNEO_NETWORK_TYPE_CAN: {
            // All messages of type CAN can be accessed using neomessage_can_t
            neomessage_can_t* canMessage = (neomessage_can_t*)&messages[i];
            printf("ArbID: 0x%x\n", canMessage->arbid);
            printf("DLC: %u\n", canMessage->length);
            printf("Data: ");
            for(size_t i = 0; i < canMessage->length; i++) {
                printf("%02x ", canMessage->data[i]);
            }
            printf("\nTimestamp: %lu\n", canMessage->timestamp);
        }
    }
}
free(messages);

Warning: Do not call icsneo_close() while another thread is waiting on icsneo_getMessages(). Always allow the other thread to timeout first!

int icsneo_getPollingMessageLimit(const neodevice_t *device)¶

Get the maximum number of messages which will be held in the API managed buffer for the specified hardware.

See

icsneo_enableMessagePolling() for more information about the message polling system.

Return

Number of messages, or -1 if device is invalid.

Parameters

device: A pointer to the neodevice_t structure specifying the device to operate on.

bool icsneo_setPollingMessageLimit(const neodevice_t *device, size_t newLimit)¶

Set the maximum number of messages which will be held in the API managed buffer for the specified hardware.

See

icsneo_enableMessagePolling() for more information about the message polling system.

Return

True if the limit was set successfully.

Parameters

device: A pointer to the neodevice_t structure specifying the device to operate on.
newLimit: The new limit to be enforced.

Setting the maximum lower than the current number of stored messages will cause the oldest messages to be dropped (LOST) and an icsneo::APIEvent::PollingMessageOverflow to be flagged for the device.

int icsneo_addMessageCallback(const neodevice_t *device, void (*callback)(neomessage_t), void *, )¶

Adds a message callback to the specified device to be called when a new message is received.

Return

The id of the callback added, or -1 if the operation failed.

Parameters

device: A pointer to the neodevice_t structure specifying the device to operate on.
callback: A function pointer with void return type and a single neomessage_t parameter.
filter: Unused for now. Exists as a placeholder here for future backwards-compatibility.

bool icsneo_removeMessageCallback(const neodevice_t *device, int id)¶

Removes a message callback from the specified device.

Return

True if the callback was successfully removed.

Parameters

device: A pointer to the neodevice_t structure specifying the device to operate on.
id: The id of the callback to remove.

bool icsneo_getProductName(const neodevice_t *device, char *str, size_t *maxLength)¶

Get the friendly product name for a specified device.

In the case of a neoVI FIRE 2, this function will write a string “neoVI FIRE 2” with a NULL terminator into str.

Return

True if str was written to

Parameters

device: A pointer to the neodevice_t structure specifying the device to operate on.
str: A pointer to a buffer where the string will be written. NULL can be passed, which will write a character count to maxLength.
maxLength: A pointer to a size_t which, prior to the call, holds the maximum number of characters to be written (so str must be of size maxLength + 1 to account for the NULL terminator), and after the call holds the number of characters written.

The constant ICSNEO_DEVICETYPE_LONGEST_NAME is defined for the client application to create static buffers of the correct length.

See also icsneo_describeDevice().

A query for length (str == NULL) will return false. icsneo_getLastError() should be checked to verify that the neodevice_t provided was valid.

If the size provided is not large enough, the output will be truncated. An icsneo::APIEvent::OutputTruncatedError will be available in icsneo_getLastError() in this case. True will still be returned.

bool icsneo_settingsRefresh(const neodevice_t *device)¶

Trigger a refresh of the settings structure for a specified device.

Return

True if the refresh succeeded.

Parameters

device: A pointer to the neodevice_t structure specifying the device to operate on.

bool icsneo_settingsApply(const neodevice_t *device)¶

Commit the settings structure for a specified device to non-volatile storage.

When modifications are made to the device settings, this function (or

icsneo_settingsApplyTemporary()) must be called to send the changes to the device and make them active.

Return

True if the settings were applied.

Parameters

device: A pointer to the neodevice_t structure specifying the device to operate on.

This function sets the settings such that they will survive device power cycles.

If the function fails, the settings will be refreshed so that the structure in the API matches the one held by the device.

bool icsneo_settingsApplyTemporary(const neodevice_t *device)¶

Apply the settings structure for a specified device temporarily.

See

icsneo_settingsApply() for further information about applying settings.

Return

True if the settings were applied.

Parameters

device: A pointer to the neodevice_t structure specifying the device to operate on.

This function sets the settings such that they will revert to the values saved in non-volatile storage when the device loses power.

bool icsneo_settingsApplyDefaults(const neodevice_t *device)¶

Apply the default settings structure for a specified device.

See

icsneo_settingsApply() for further information about applying settings.

Return

True if the default settings were applied.

Parameters

device: A pointer to the neodevice_t structure specifying the device to operate on.

This function sets the default settings such that they will survive device power cycles.

bool icsneo_settingsApplyDefaultsTemporary(const neodevice_t *device)¶

Apply the default settings structure for a specified device temporarily.

See

icsneo_settingsApply() for further information about applying settings. See icsneo_settingsApplyDefaults() for further information about applying default settings.

Return

True if the default settings were applied.

Parameters

device: A pointer to the neodevice_t structure specifying the device to operate on.

This function sets the default settings such that they will revert to the values saved in non-volatile storage when the device loses power.

int icsneo_settingsReadStructure(const neodevice_t *device, void *structure, size_t structureSize)¶

Apply the default settings structure for a specified device temporarily.

See

icsneo_settingsApply() for further information about applying settings. See icsneo_settingsApplyDefaults() for further information about applying default settings.

Return

Number of bytes written to structure, or -1 if the operation failed.

Parameters

device: A pointer to the neodevice_t structure specifying the device to operate on.
structure: A pointer to a device settings structure for the current device.
structureSize: The size of the current device settings structure in bytes.

This function sets the default settings such that they will revert to the values saved in non-volatile storage when the device loses power.

If possible, use functions specific to the operation you want to acomplish (such as icsneo_setBaudrate()) instead of modifying the structure directly. This allows the client application to work with other hardware.

bool icsneo_settingsApplyStructure(const neodevice_t *device, const void *structure, size_t structureSize)¶

Apply a provided settings structure for a specified device.

This function immediately applies the provided settings. See

icsneo_settingsApplyTemporary() for further information about applying settings.

Return

True if the settings were applied.

Parameters

device: A pointer to the neodevice_t structure specifying the device to operate on.
structure: A pointer to a device settings structure for the current device.
structureSize: The size of the current device settings structure in bytes.

If possible, use functions specific to the operation you want to acomplish (such as icsneo_setBaudrate()) instead of modifying the structure directly. This allows the client application to work with other hardware.

bool icsneo_settingsApplyStructureTemporary(const neodevice_t *device, const void *structure, size_t structureSize)¶

Apply a provided settings structure for a specified device without saving to non-volatile EEPROM.

This function immediately applies the provided settings. See

icsneo_settingsApply() for further information about applying settings.

Return

True if the settings were applied.

Parameters

device: A pointer to the neodevice_t structure specifying the device to operate on.
structure: A pointer to a device settings structure for the current device.
structureSize: The size of the current device settings structure in bytes.

This function sets the default settings such that they will revert to the values saved in non-volatile storage when the device loses power.

If possible, use functions specific to the operation you want to acomplish (such as icsneo_setBaudrate()) instead of modifying the structure directly. This allows the client application to work with other hardware.

int64_t icsneo_getBaudrate(const neodevice_t *device, uint16_t netid)¶

Get the network baudrate for a specified device.

In the case of CAN, this function gets the standard CAN baudrate. See

icsneo_getFDBaudrate() to get the baudrate for (the baudrate-switched portion of) CAN FD.

Return

The value in baud with no multipliers. (i.e. 500k becomes 500000) A negative value is returned if an error occurs.

Parameters

device: A pointer to the neodevice_t structure specifying the device to operate on.
netid: The network for which the baudrate should be retrieved.

bool icsneo_setBaudrate(const neodevice_t *device, uint16_t netid, int64_t newBaudrate)¶

Set the network baudrate for a specified device.

In the case of CAN, this function sets the standard CAN baudrate. See

icsneo_setFDBaudrate() to set the baudrate for (the baudrate-switched portion of) CAN FD.

Return

True if the baudrate could be set.

Parameters

device: A pointer to the neodevice_t structure specifying the device to operate on.
netid: The network to which the new baudrate should apply.
newBaudrate: The requested baudrate, with no multipliers. (i.e. 500K CAN should be represented as 500000)

Call icsneo_settingsApply() or similar to make the changes active on the device.

int64_t icsneo_getFDBaudrate(const neodevice_t *device, uint16_t netid)¶

Get the CAN FD baudrate for a specified device.

See

icsneo_getBaudrate() to get the baudrate for the non baudrate-switched portion of CAN FD, classical CAN 2.0, and other network types.

Return

The value in baud with no multipliers. (i.e. 500k becomes 500000) A negative value is returned if an error occurs.

Parameters

device: A pointer to the neodevice_t structure specifying the device to operate on.
netid: The network for which the baudrate should be retrieved.

bool icsneo_setFDBaudrate(const neodevice_t *device, uint16_t netid, int64_t newBaudrate)¶

Set the CAN FD baudrate for a specified device.

See

icsneo_setBaudrate() to set the baudrate for the non baudrate-switched portion of CAN FD, classical CAN 2.0, and other network types.

Return

True if the baudrate could be set.

Parameters

device: A pointer to the neodevice_t structure specifying the device to operate on.
netid: The network to which the new baudrate should apply.
newBaudrate: The requested baudrate, with no multipliers. (i.e. 2Mbaud CAN FD should be represented as 2000000)

Call icsneo_settingsApply() or similar to make the changes active on the device.

bool icsneo_transmit(const neodevice_t *device, const neomessage_t *message)¶

Transmit a single message.

To transmit a message, you must set the

data, length, and netid attributes of the neomessage_t.

Return

True if the message was verified transmittable and enqueued for transmit.

Parameters

device: A pointer to the neodevice_t structure specifying the device to transmit on.
message: A pointer to the neomessage_t structure defining the message.

The data attribute must be set to a pointer to a buffer of at least length which holds the payload bytes. This buffer only needs to be valid for the duration of this call, and can safely be deallocated or reused after the return.

You may also have to set network dependent variables. For CAN, you must set the arbid attribute defined in neomessage_can_t.

Other attributes of the neomessage_t such as timestamp, type and reserved which are not used should be set to 0. Unused status bits should also be set to 0.

Any types defined neomessage_*_t are designed to be binary compatible with neomessage_t.

For instance, for CAN, it is recommended to use neomessage_can_t as it exposes the arbid field.

neomessage_can_t mySendMessage = {}; // Zero all before use
uint8_t myData[3] = { 0xAA, 0xBB, 0xCC }; // Either heap or stack allocated is okay
mySendMessage.netid = ICSNEO_NETID_HSCAN;
mySendMessage.arbid = 0x1c5001c5;
mySendMessage.length = 3;
mySendMessage.data = myData;
mySendMessage.status.canfdFDF = true; // CAN FD
mySendMessage.status.extendedFrame = true; // Extended (29-bit) arbitration IDs
mySendMessage.status.canfdBRS = true; // CAN FD Baudrate Switch
bool result = icsneo_transmit(device, (neomessage_t*)&mySendMessage);

myData[1] = 0x55; // The message and buffer can be safely reused for the next message
result = icsneo_transmit(device, (neomessage_t*)&mySendMessage);

bool icsneo_transmitMessages(const neodevice_t *device, const neomessage_t *messages, size_t count)¶

Transmit a multiple messages.

See

icsneo_transmit() for information regarding transmitting messages.

Return

True if the messages were verified transmittable and enqueued for transmit.

Parameters

device: A pointer to the neodevice_t structure specifying the device to transmit on.
messages: A pointer to the neomessage_t structures defining the messages.
count: The number of messages to transmit.

On a per-network basis, messages will be transmitted in the order that they were enqueued.

In this case, messages will be enqueued in order of increasing index.

void icsneo_setWriteBlocks(const neodevice_t *device, bool blocks)¶

Set the behavior of whether writing is a blocking action or not.

By default, writing is a blocking action.

Parameters

device: A pointer to the neodevice_t structure specifying the device to transmit on.
blocks: Whether or not writing is a blocking action.

bool icsneo_describeDevice(const neodevice_t *device, char *str, size_t *maxLength)¶

Get the friendly description for a specified device.

In the case of a neoVI FIRE 2 with serial number CY2285, this function will write a string “neoVI FIRE 2 CY2285” with a NULL terminator into str.

Return

True if str was written to

Parameters

device: A pointer to the neodevice_t structure specifying the device to operate on.
str: A pointer to a buffer where the string will be written. NULL can be passed, which will write a character count to maxLength.
maxLength: A pointer to a size_t which, prior to the call, holds the maximum number of characters to be written (so str must be of size maxLength + 1 to account for the NULL terminator), and after the call holds the number of characters written.

The constant ICSNEO_DEVICETYPE_LONGEST_DESCRIPTION is defined for the client application to create static buffers of the correct length.