C API

Functions

void DLLExport 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.

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.

Parameters:

devices – [out] Pointer to memory where devices should be written. If NULL, the current number of detected devices is written to count.
count – [inout] 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.

void DLLExport icsneo_freeUnconnectedDevices (void)

Invalidate neodevice_t objects which have not been opened.

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

bool DLLExport 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.

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.

Parameters:

num – [in] A numerical serial number.
str – [out] 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 – [inout] 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.

Returns:

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

uint32_t DLLExport 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.

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

Parameters:: str – [in] A NULL terminated string containing the string representation of an Intrepid serial number.
Returns:: The numerical representation of the serial number, or 0 if the conversion was unsuccessful.

bool DLLExport 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().

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

Parameters:: device – [in] A pointer to the neodevice_t structure to operate on.
Returns:: True if the neodevice_t is valid.

bool DLLExport 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.

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().

Parameters:: device – [in] A pointer to the neodevice_t structure specifying the device to open.
Returns:: True if the connection could be opened.

bool DLLExport 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.

Parameters:: device – [in] A pointer to the neodevice_t structure specifying the device to close.
Returns:: True if the connection could be closed.

bool DLLExport 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.

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

Parameters:: device – [in] A pointer to the neodevice_t structure specifying the device to operate on.
Returns:: True if the device is connected.

bool DLLExport 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)

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.

Parameters:: device – [in] A pointer to the neodevice_t structure specifying the device to operate on.
Returns:: True if communication could be enabled.

bool DLLExport 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”.

Parameters:: device – [in] A pointer to the neodevice_t structure specifying the device to operate on.
Returns:: True if communication could be disabled.

bool DLLExport 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.

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

Parameters:: device – [in] A pointer to the neodevice_t structure specifying the device to operate on.
Returns:: True if communication is enabled.

bool DLLExport 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.

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.

Parameters:: device – [in] A pointer to the neodevice_t structure specifying the device to operate on.
Returns:: True if polling could be enabled.

bool DLLExport 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.

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

Parameters:: device – [in] A pointer to the neodevice_t structure specifying the device to operate on.
Returns:: True if polling could be disabled.

bool DLLExport 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.

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

Parameters:: device – [in] A pointer to the neodevice_t structure specifying the device to operate on.
Returns:: True if polling is enabled.

bool DLLExport 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.

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.

 C
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!

Parameters:

device – [in] A pointer to the neodevice_t structure specifying the device to operate on.
messages – [out] 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 – [inout] 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 – [in] 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.

Returns:

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

int DLLExport 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.

Parameters:: device – [in] A pointer to the neodevice_t structure specifying the device to operate on.
Returns:: Number of messages, or -1 if device is invalid.

bool DLLExport 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.

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.

Parameters:

device – [in] A pointer to the neodevice_t structure specifying the device to operate on.
newLimit – [in] The new limit to be enforced.

Returns:

True if the limit was set successfully.

int DLLExport 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.

Parameters:

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

Returns:

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

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

Removes a message callback from the specified device.

Parameters:

device – [in] A pointer to the neodevice_t structure specifying the device to operate on.
id – [in] The id of the callback to remove.

Returns:

True if the callback was successfully removed.

neonetid_t DLLExport icsneo_getNetworkByNumber (const neodevice_t *device, neonettype_t type, unsigned int number)

Get the network ID for the nth network of a specified type on this device.

This function is designed so that networks can be enumerated without knowledge of the specific device. For instance, on a ValueCAN 4-2, the second CAN network is ICSNEO_NETID_DWCAN_02, while on a neoVI FIRE the second CAN network is ICSNEO_NETID_DWCAN_08.

Parameters:

device – [in] A pointer to the neodevice_t structure specifying the device to operate on.
type – [in] An ICSNEO_NETWORK_TYPE_* constant denoting the network type
number – [in] The number of this network starting from 1

Returns:

The netid if the call succeeds, ICSNEO_NETID_INVALID otherwise

bool DLLExport 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.

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.

Parameters:

type – [in] A neodevice_t structure specifying the device to operate on.
str – [out] A pointer to a buffer where the string will be written. NULL can be passed, which will write a character count to maxLength.
maxLength – [inout] 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.

Returns:

True if str was written to

bool DLLExport icsneo_settingsRefresh (const neodevice_t *device)

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

Parameters:: device – [in] A pointer to the neodevice_t structure specifying the device to operate on.
Returns:: True if the refresh succeeded.

bool DLLExport 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.

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.

Parameters:: device – [in] A pointer to the neodevice_t structure specifying the device to operate on.
Returns:: True if the settings were applied.

bool DLLExport icsneo_settingsApplyTemporary (const neodevice_t *device)

Apply the settings structure for a specified device temporarily.

See icsneo_settingsApply() for further information about applying settings.

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

Parameters:: device – [in] A pointer to the neodevice_t structure specifying the device to operate on.
Returns:: True if the settings were applied.

bool DLLExport icsneo_settingsApplyDefaults (const neodevice_t *device)

Apply the default settings structure for a specified device.

See icsneo_settingsApply() for further information about applying settings.

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

Parameters:: device – [in] A pointer to the neodevice_t structure specifying the device to operate on.
Returns:: True if the default settings were applied.

bool DLLExport 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.

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

Parameters:: device – [in] A pointer to the neodevice_t structure specifying the device to operate on.
Returns:: True if the default settings were applied.

int DLLExport 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.

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.

Parameters:

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

Returns:

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

bool DLLExport 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.

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.

Parameters:

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

Returns:

True if the settings were applied.

bool DLLExport 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.

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.

Parameters:

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

Returns:

True if the settings were applied.

int64_t DLLExport icsneo_getBaudrate (const neodevice_t *device, neonetid_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.

Parameters:

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

Returns:

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

bool DLLExport icsneo_setBaudrate (const neodevice_t *device, neonetid_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.

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

Parameters:

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

Returns:

True if the baudrate could be set.

int64_t DLLExport icsneo_getFDBaudrate (const neodevice_t *device, neonetid_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.

Parameters:

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

Returns:

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

bool DLLExport icsneo_setFDBaudrate (const neodevice_t *device, neonetid_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.

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

Parameters:

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

Returns:

True if the baudrate could be set.

bool DLLExport 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.

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.

 C
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_DWCAN_01;
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);

Parameters:

device – [in] A pointer to the neodevice_t structure specifying the device to transmit on.
message – [in] A pointer to the neomessage_t structure defining the message.

Returns:

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

bool DLLExport 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.

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.

Parameters:

device – [in] A pointer to the neodevice_t structure specifying the device to transmit on.
messages – [in] A pointer to the neomessage_t structures defining the messages.
count – [in] The number of messages to transmit.

Returns:

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

void DLLExport 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 – [in] A pointer to the neodevice_t structure specifying the device to transmit on.
blocks – [in] Whether or not writing is a blocking action.

bool DLLExport 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.

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