MIP_SDK  latest-2-g34f3e39
MicroStrain Communications Library for embedded systems
Classes | Typedefs | Functions
Mip Interface

High-level C functions for controlling a MIP device. More...

Classes

struct  mip::C::mip_interface
 State of the interface for communicating with a MIP device. More...
 

Typedefs

typedef bool(* mip::C::mip_send_callback) (struct mip_interface *device, const uint8_t *data, size_t length)
 Called from mip_interface_send_to_device() to send data to the device port. The application should forward the data to the device port (e.g. a serial port, TCP connection, etc). More...
 
typedef bool(* mip::C::mip_recv_callback) (struct mip_interface *device, mip_timeout wait_time, bool from_cmd, mip_timestamp *timestamp_out)
 Called from mip_interface_recv_from_device() to receive data from the device port. More...
 
typedef bool(* mip::C::mip_update_callback) (struct mip_interface *device, mip_timeout wait_time, bool from_cmd)
 Callback function typedef for custom update behavior. More...
 
typedef struct mip::C::mip_interface mip::C::mip_interface
 State of the interface for communicating with a MIP device. More...
 

Functions

void mip::C::mip_interface_init (mip_interface *device, mip_timeout parse_timeout, mip_timeout base_reply_timeout, mip_send_callback send, mip_recv_callback recv, mip_update_callback update, void *user_pointer)
 Initialize the mip_interface components. More...
 
bool mip::C::mip_interface_send_to_device (mip_interface *device, const uint8_t *data, size_t length)
 Sends data to the port (i.e. from this library to the physical device). More...
 
bool mip::C::mip_interface_recv_from_device (mip_interface *device, mip_timeout wait_time, bool from_cmd, mip_timestamp *timestamp_out)
 Checks for data at the port and reads it into buffer. More...
 
bool mip::C::mip_interface_update (struct mip_interface *device, mip_timeout wait_time, bool from_cmd)
 Call to process data from the device. More...
 
bool mip::C::mip_interface_default_update (struct mip_interface *device, mip_timeout wait_time, bool from_cmd)
 Polls the port for new data or command replies. More...
 
void mip::C::mip_interface_input_bytes (mip_interface *device, const uint8_t *data, size_t length, mip_timestamp timestamp)
 Passes data from the device into the parser. More...
 
void mip::C::mip_interface_input_packet (mip_interface *device, const mip_packet_view *packet, mip_timestamp timestamp)
 Processes a pre-parsed packet for command replies and data. More...
 
void mip::C::mip_interface_parse_callback (void *device, const mip_packet_view *packet, mip_timestamp timestamp)
 Wrapper around mip_interface_input_packet for use with mip_parser. More...
 
enum mip_cmd_result mip::C::mip_interface_wait_for_reply (mip_interface *device, mip_pending_cmd *cmd)
 Blocks until the pending command completes or times out. More...
 
enum mip_cmd_result mip::C::mip_interface_run_command (mip_interface *device, uint8_t descriptor_set, uint8_t cmd_descriptor, const uint8_t *cmd_data, uint8_t cmd_length)
 Runs a command using a pre-serialized payload. More...
 
enum mip_cmd_result mip::C::mip_interface_run_command_with_response (mip_interface *device, uint8_t descriptor_set, uint8_t cmd_descriptor, const uint8_t *cmd_data, uint8_t cmd_length, uint8_t response_descriptor, uint8_t *response_buffer, uint8_t *response_length_inout)
 Runs a command using a pre-serialized payload. More...
 
enum mip_cmd_result mip::C::mip_interface_run_command_packet (mip_interface *device, const mip_packet_view *packet, mip_pending_cmd *cmd)
 Similar to mip_interface_start_command_packet but waits for the command to complete. More...
 
bool mip::C::mip_interface_start_command_packet (mip_interface *device, const mip_packet_view *packet, mip_pending_cmd *cmd)
 Queues the command and sends the packet. Does not wait for completion. More...
 
void mip::C::mip_interface_register_packet_callback (mip_interface *device, mip_dispatch_handler *handler, uint8_t descriptor_set, bool after_fields, mip_dispatch_packet_callback callback, void *user_data)
 Registers a callback for packets of the specified descriptor set. More...
 
void mip::C::mip_interface_register_field_callback (mip_interface *device, mip_dispatch_handler *handler, uint8_t descriptor_set, uint8_t field_descriptor, mip_dispatch_field_callback callback, void *user_data)
 Registers a callback for packets of the specified descriptor set. More...
 
void mip::C::mip_interface_register_extractor (mip_interface *device, mip_dispatch_handler *handler, uint8_t descriptor_set, uint8_t field_descriptor, mip_dispatch_extractor extractor, void *field_ptr)
 Registers a callback for packets of the specified descriptor set. More...
 
void mip::C::mip_interface_set_recv_function (mip_interface *device, mip_recv_callback callback)
 Sets the receive callback function. More...
 
void mip::C::mip_interface_set_send_function (mip_interface *device, mip_send_callback callback)
 Sets the send callback function. More...
 
void mip::C::mip_interface_set_update_function (mip_interface *device, mip_update_callback callback)
 Sets the update function. More...
 
void mip::C::mip_interface_set_user_pointer (mip_interface *device, void *pointer)
 Sets an optional user data pointer which can be retrieved later. More...
 
mip_recv_callback mip::C::mip_interface_recv_function (const mip_interface *device)
 Gets the receive function pointer. More...
 
mip_send_callback mip::C::mip_interface_send_function (const mip_interface *device)
 Gets the send function pointer. More...
 
mip_update_callback mip::C::mip_interface_update_function (const mip_interface *device)
 Gets the update function pointer. More...
 
void * mip::C::mip_interface_user_pointer (const mip_interface *device)
 Retrieves the pointer set by mip_interface_set_user_pointer(). More...
 
mip_parsermip::C::mip_interface_parser (mip_interface *device)
 Returns the MIP parser for the device. More...
 
mip_cmd_queuemip::C::mip_interface_cmd_queue (mip_interface *device)
 Returns the commmand queue for the device. More...
 

Detailed Description

High-level C functions for controlling a MIP device.

This module contains functions and classes for communicating with a MIP device in C.

Typedef Documentation

◆ mip_interface

State of the interface for communicating with a MIP device.

◆ mip_recv_callback

mip::C::mip_recv_callback

Called from mip_interface_recv_from_device() to receive data from the device port.

This is called indirectly through mip_interface_update() to poll for new data and command responses. For single-threaded applications, it will be called while waiting for command replies.

Parameters
deviceA pointer to the device interface. Applications can use the user data pointer to access additional information such as the port handle.
wait_timeTime to wait for data from the device. The actual time waited may be less than wait_time, but it should not significantly exceed this value.
from_cmdIf true, this call is a result of waiting for a command to complete. Otherwise, this call is a regularly- scheduled poll for data.
timestamp_outTimestamp of the data that was received.
Returns
True if successful, even if no data is received.
False if the port cannot be read or some other error occurs (e.g. if the port is closed). If this function returns false when from_cmd is true, the corresponding command will fail with MIP_STATUS_ERROR.
Note
Except in case of error (i.e. returning false), the timestamp must be set even if no data is received. This is required to allow commands to time out when no response is received.
Applications may sleep the thread or enter a low-power state while waiting for data. On posix-like (e.g. desktop) systems, applications should call read() with a maximum timeout of wait_time. If the actual wait time is less than the requested duration, this function may be called again by the MIP SDK to wait the remaining time. If the actual wait time exceeds wait_time, command timeouts may take longer than intended.
See also
mip_interface_recv_from_device

◆ mip_send_callback

mip::C::mip_send_callback

Called from mip_interface_send_to_device() to send data to the device port. The application should forward the data to the device port (e.g. a serial port, TCP connection, etc).

Parameters
deviceA pointer to the device interface. Applications can use the user data pointer to access additional information such as the port handle.
dataBuffer containing the data to be transmitted to the device.
lengthLength of data to transmit.
Returns
True if all of the data was successfully transmitted.
False if an error occurred and some or all data was definitely unable to be transmitted.
Applications should prefer returning true if success is uncertain since command timeouts will help detect failed transmissions. If this function returns false, the associated command will fail with CmdResult::STATUS_ERROR. Commands will time out in case of undetected transmission failures, so false positives are OK. False negatives will cause commands to immediately fail even if sent successfully however, and the unexpected ack/nack replies increase the risk of confusing which replies go with which commands.

◆ mip_update_callback

mip::C::mip_update_callback

Callback function typedef for custom update behavior.

This function is called whenever data should be parsed from the port:

  • While waiting for command responses
  • To check for new data packets

Generally an application should call mip_interface_recv_from_device() from within this callback and pass the data to mip_interface_input_bytes(). Many applications can set this callback to mip_interface_default_update().

Parameters
deviceThe mip_interface object being updated.
timeoutApproximate amount of time to wait for data from the device. This may be an underestimate, but applications should not wait significantly longer as this may cause commands to take longer to time out.
from_cmdIf true, this call is a result of waiting for a command to complete. Otherwise, this call is a regularly-scheduled poll for data. Typically an application will not wait for more data if this is false, or may sleep while waiting if this is true.
Returns
True if successful (even if no data is received).
False if an error occurs and the port cannot be read (e.g. if the port is closed). Returning false will cause any pending commands to fail with a status error code.
Note
This update call should not return false (i.e. failure) when from_cmd is true and reception is handled by another thread, unless that thread is not currently running. Otherwise a race condition may occur in the command queue.

Function Documentation

◆ mip_interface_cmd_queue()

mip_cmd_queue * mip::C::mip_interface_cmd_queue ( mip_interface device)

Returns the commmand queue for the device.

◆ mip_interface_default_update()

bool mip::C::mip_interface_default_update ( struct mip_interface device,
mip_timeout  wait_time,
bool  from_cmd 
)

Polls the port for new data or command replies.

This is the default choice for the user update function. It ignores the from_cmd flag and always reads data from the device.

Parameters
device
wait_timeTime to wait for data from the device. This will be nonzero when waiting for command replies. Applications calling this function can pass 0 to avoid blocking when checking for new data.
from_cmdIf true, this call is a result of waiting for a command to complete. Otherwise, this call is a regularly-scheduled poll for data. User code calling this function should generally set this to false.
Returns
The value returned by mip_interface_user_recv_from_device.

◆ mip_interface_init()

void mip::C::mip_interface_init ( mip_interface device,
mip_timeout  parse_timeout,
mip_timeout  base_reply_timeout,
mip_send_callback  send,
mip_recv_callback  recv,
mip_update_callback  update,
void *  user_pointer 
)

Initialize the mip_interface components.

Parameters
device
parse_timeoutMaximum length of time to wait for the end of a MIP packet. See mip_parser_init().
base_reply_timeoutMinimum time for all commands. See mip_cmd_queue_init().
sendA callback which is called to send data to the device.
recvA callback which is called when data needs to be read from the device.
updateOptional callback which is called to perform routine tasks such as checking for command timeouts. Defaults to mip_interface_default_update.
user_pointerOptional pointer which is passed to the send, recv, and update callbacks.

◆ mip_interface_input_bytes()

void mip::C::mip_interface_input_bytes ( mip_interface device,
const uint8_t *  data,
size_t  length,
mip_timestamp  timestamp 
)

Passes data from the device into the parser.

Parameters
device
dataInput data buffer. May be NULL if length == 0.
lengthLength of the input buffer. Must be 0 if data is NULL.
timestampTime of the received data.

◆ mip_interface_input_packet()

void mip::C::mip_interface_input_packet ( mip_interface device,
const mip_packet_view packet,
mip_timestamp  timestamp 
)

Processes a pre-parsed packet for command replies and data.

Parameters
device
packetThe received MIP packet.
timestampTimestamp of the received MIP packet.

◆ mip_interface_parse_callback()

void mip::C::mip_interface_parse_callback ( void *  device,
const mip_packet_view packet,
mip_timestamp  timestamp 
)

Wrapper around mip_interface_input_packet for use with mip_parser.

Parameters
deviceVoid pointer to the device. Must be a mip_interface pointer.
packetMIP Packet from the parser.
timestampTimestamp of the packet.

◆ mip_interface_parser()

mip_parser * mip::C::mip_interface_parser ( mip_interface device)

Returns the MIP parser for the device.

◆ mip_interface_recv_from_device()

bool mip::C::mip_interface_recv_from_device ( mip_interface device,
mip_timeout  wait_time,
bool  from_cmd,
mip_timestamp timestamp_out 
)

Checks for data at the port and reads it into buffer.

Parameters
device
bufferA place to store the data.
max_lengthMaximum number of bytes to read into buffer.
wait_timeMaximum time to wait for data. May be 0.
length_outThe number of bytes successfully read into buffer.
timestamp_outThe timestamp of the received data.
Returns
True if successful (even if 0 bytes were read).
False if the receive callback is NULL.
False if the receive callback failed (i.e. if it returned false).

◆ mip_interface_recv_function()

mip_recv_callback mip::C::mip_interface_recv_function ( const mip_interface device)

Gets the receive function pointer.

Parameters
device
Returns
The receive callback function. May be NULL.

◆ mip_interface_register_extractor()

void mip::C::mip_interface_register_extractor ( mip_interface device,
mip_dispatch_handler handler,
uint8_t  descriptor_set,
uint8_t  field_descriptor,
mip_dispatch_extractor  extractor,
void *  field_ptr 
)

Registers a callback for packets of the specified descriptor set.

Parameters
device
handlerAn uninitialized mip_dispatch_handler object. This call will initialize it.
descriptor_set
field_descriptor
extractor
field_ptr
See also
mip_dispatch_handler_init_extract_handler for details.

◆ mip_interface_register_field_callback()

void mip::C::mip_interface_register_field_callback ( mip_interface device,
mip_dispatch_handler handler,
uint8_t  descriptor_set,
uint8_t  field_descriptor,
mip_dispatch_field_callback  callback,
void *  user_data 
)

Registers a callback for packets of the specified descriptor set.

Parameters
device
handlerAn uninitialized mip_dispatch_handler object. This call will initialize it.
descriptor_set
field_descriptor
callback
user_data
See also
mip_dispatch_handler_init_field_handler for details.

◆ mip_interface_register_packet_callback()

void mip::C::mip_interface_register_packet_callback ( mip_interface device,
mip_dispatch_handler handler,
uint8_t  descriptor_set,
bool  after_fields,
mip_dispatch_packet_callback  callback,
void *  user_data 
)

Registers a callback for packets of the specified descriptor set.

Parameters
device
handlerAn uninitialized mip_dispatch_handler object. This call will initialize it.
descriptor_set
after_fields
callback
user_data
See also
mip_dispatch_handler_init_packet_handler for details.

◆ mip_interface_run_command()

enum mip_cmd_result mip::C::mip_interface_run_command ( mip_interface device,
uint8_t  descriptor_set,
uint8_t  cmd_descriptor,
const uint8_t *  cmd_data,
uint8_t  cmd_length 
)

Runs a command using a pre-serialized payload.

Parameters
device
descriptor_setCommand descriptor set.
cmd_descriptorCommand field descriptor.
cmd_dataOptional payload data. May be NULL if cmd_length == 0.
cmd_lengthLength of the command payload (parameters).
Returns
mip_cmd_result MIP_ACK_OK - Command completed successfully. MIP_NACK_* - Device rejected the command. MIP_STATUS_* - An error occured (e.g. timeout).

◆ mip_interface_run_command_packet()

enum mip_cmd_result mip::C::mip_interface_run_command_packet ( mip_interface device,
const mip_packet_view packet,
mip_pending_cmd cmd 
)

Similar to mip_interface_start_command_packet but waits for the command to complete.

Parameters
device
packetA MIP packet containing the command.
cmdThe command status tracker. No lifetime requirement.

◆ mip_interface_run_command_with_response()

enum mip_cmd_result mip::C::mip_interface_run_command_with_response ( mip_interface device,
uint8_t  descriptor_set,
uint8_t  cmd_descriptor,
const uint8_t *  cmd_data,
uint8_t  cmd_length,
uint8_t  response_descriptor,
uint8_t *  response_buffer,
uint8_t *  response_length_inout 
)

Runs a command using a pre-serialized payload.

Parameters
device
descriptor_setCommand descriptor set.
cmd_descriptorCommand field descriptor.
cmd_dataOptional payload data. May be NULL if cmd_length == 0.
cmd_lengthLength of the command payload (parameters).
response_descriptorDescriptor of the response data. May be MIP_INVALID_FIELD_DESCRIPTOR if no response is expected.
response_bufferBuffer to hold response data. Can be the same as the command data buffer. Can be NULL if response_descriptor is MIP_INVALID_FIELD_DESCRIPTOR.
[in,out]response_length_inoutAs input, the size of response buffer and max response length. As output, returns the actual length of the response data.
Returns
mip_cmd_result

◆ mip_interface_send_function()

mip_send_callback mip::C::mip_interface_send_function ( const mip_interface device)

Gets the send function pointer.

Parameters
device
Returns
The send callback function. May be NULL.

◆ mip_interface_send_to_device()

bool mip::C::mip_interface_send_to_device ( mip_interface device,
const uint8_t *  data,
size_t  length 
)

Sends data to the port (i.e. from this library to the physical device).

Parameters
deviceThe mip_interface object.
dataData to be sent.
lengthLength of data.
Returns
True if the data was sent successfully.
False if the send callback is NULL.
False if some or all data could not be sent.

This is called whenever bytes must be sent to the physical device.

◆ mip_interface_set_recv_function()

void mip::C::mip_interface_set_recv_function ( mip_interface device,
mip_recv_callback  callback 
)

Sets the receive callback function.

Parameters
device
callbackFunction which gets data from the device connection. If this is NULL then commands will fail and no data will be received.

◆ mip_interface_set_send_function()

void mip::C::mip_interface_set_send_function ( mip_interface device,
mip_send_callback  callback 
)

Sets the send callback function.

Parameters
device
callbackFunction which sends raw bytes to the device. This can be NULL if no commands will be issued (they would fail).

◆ mip_interface_set_update_function()

void mip::C::mip_interface_set_update_function ( mip_interface device,
mip_update_callback  callback 
)

Sets the update function.

By default, the update function is mip_interface_default_update.

See also
mip_update_callback
mip_interface_update
Parameters
device
callbackUpdate function to call when polling the device for data. If this is NULL, then update calls will fail and no data or or command replies will be received.

◆ mip_interface_set_user_pointer()

void mip::C::mip_interface_set_user_pointer ( mip_interface device,
void *  pointer 
)

Sets an optional user data pointer which can be retrieved later.

Parameters
device
pointer

◆ mip_interface_start_command_packet()

bool mip::C::mip_interface_start_command_packet ( mip_interface device,
const mip_packet_view packet,
mip_pending_cmd cmd 
)

Queues the command and sends the packet. Does not wait for completion.

Parameters
device
packetA MIP packet containing the command.
cmdThe command status tracker. Must be valid while the command executes.
Returns
True if successful. Cmd must remain valid until the command finishes.
False on error sending the packet. No cleanup is necessary and cmd can be destroyed immediately afterward in this case.

◆ mip_interface_update()

bool mip::C::mip_interface_update ( struct mip_interface device,
mip_timeout  wait_time,
bool  from_cmd 
)

Call to process data from the device.

This function is also called while waiting for command replies.

Call this periodically to process packets received from the device. It should be called at a suitably high rate to prevent the connection buffers from overflowing. The update rate affects the reception timestamp resolution.

Parameters
device
wait_timeTime to wait for data from the device. This will be nonzero when waiting for command replies. Applications calling this function can pass 0 to avoid blocking when checking for new data.
from_cmdIf true, this call is a result of waiting for a command to complete. Otherwise, this call is a regularly-scheduled poll for data. User code calling this function should generally set this to false.
Returns
true if operation should continue, or false if the device cannot be updated (e.g. if the serial port is not open).

◆ mip_interface_update_function()

mip_update_callback mip::C::mip_interface_update_function ( const mip_interface device)

Gets the update function pointer.

Returns
The update function. Defaults to mip_interface_default_update. May be NULL.

◆ mip_interface_user_pointer()

void * mip::C::mip_interface_user_pointer ( const mip_interface device)

Retrieves the pointer set by mip_interface_set_user_pointer().

Parameters
device
Returns
The pointer value.

◆ mip_interface_wait_for_reply()

enum mip_cmd_result mip::C::mip_interface_wait_for_reply ( mip_interface device,
mip_pending_cmd cmd 
)

Blocks until the pending command completes or times out.

Parameters
device
cmd
Returns
The final status of the command.