MIP_SDK
latest-2-g34f3e39
MicroStrain Communications Library for embedded systems
|
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_parser * | mip::C::mip_interface_parser (mip_interface *device) |
Returns the MIP parser for the device. More... | |
mip_cmd_queue * | mip::C::mip_interface_cmd_queue (mip_interface *device) |
Returns the commmand queue for the device. More... | |
High-level C functions for controlling a MIP device.
This module contains functions and classes for communicating with a MIP device in C.
typedef struct mip::C::mip_interface mip::C::mip_interface |
State of the interface for communicating with a MIP device.
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.
device | A pointer to the device interface. Applications can use the user data pointer to access additional information such as the port handle. |
wait_time | Time 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_cmd | If true, this call is a result of waiting for a command to complete. Otherwise, this call is a regularly- scheduled poll for data. |
timestamp_out | Timestamp of the data that was received. |
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).
device | A pointer to the device interface. Applications can use the user data pointer to access additional information such as the port handle. |
data | Buffer containing the data to be transmitted to the device. |
length | Length of data to transmit. |
mip::C::mip_update_callback |
Callback function typedef for custom update behavior.
This function is called whenever data should be parsed from the port:
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().
device | The mip_interface object being updated. |
timeout | Approximate 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_cmd | If 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. |
mip_cmd_queue * mip::C::mip_interface_cmd_queue | ( | mip_interface * | device | ) |
Returns the commmand queue for the device.
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.
device | |
wait_time | Time 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_cmd | If 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. |
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.
device | |
parse_timeout | Maximum length of time to wait for the end of a MIP packet. See mip_parser_init(). |
base_reply_timeout | Minimum time for all commands. See mip_cmd_queue_init(). |
send | A callback which is called to send data to the device. |
recv | A callback which is called when data needs to be read from the device. |
update | Optional callback which is called to perform routine tasks such as checking for command timeouts. Defaults to mip_interface_default_update. |
user_pointer | Optional pointer which is passed to the send, recv, and update callbacks. |
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.
device | |
data | Input data buffer. May be NULL if length == 0. |
length | Length of the input buffer. Must be 0 if data is NULL. |
timestamp | Time of the received data. |
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.
device | |
packet | The received MIP packet. |
timestamp | Timestamp of the received MIP packet. |
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.
device | Void pointer to the device. Must be a mip_interface pointer. |
packet | MIP Packet from the parser. |
timestamp | Timestamp of the packet. |
mip_parser * mip::C::mip_interface_parser | ( | mip_interface * | device | ) |
Returns the MIP parser for the 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.
device | |
buffer | A place to store the data. |
max_length | Maximum number of bytes to read into buffer. |
wait_time | Maximum time to wait for data. May be 0. |
length_out | The number of bytes successfully read into buffer. |
timestamp_out | The timestamp of the received data. |
mip_recv_callback mip::C::mip_interface_recv_function | ( | const mip_interface * | device | ) |
Gets the receive function pointer.
device |
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.
device | |
handler | An uninitialized mip_dispatch_handler object. This call will initialize it. |
descriptor_set | |
field_descriptor | |
extractor | |
field_ptr |
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.
device | |
handler | An uninitialized mip_dispatch_handler object. This call will initialize it. |
descriptor_set | |
field_descriptor | |
callback | |
user_data |
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.
device | |
handler | An uninitialized mip_dispatch_handler object. This call will initialize it. |
descriptor_set | |
after_fields | |
callback | |
user_data |
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.
device | |
descriptor_set | Command descriptor set. |
cmd_descriptor | Command field descriptor. |
cmd_data | Optional payload data. May be NULL if cmd_length == 0. |
cmd_length | Length of the command payload (parameters). |
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.
device | |
packet | A MIP packet containing the command. |
cmd | The command status tracker. No lifetime requirement. |
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.
device | ||
descriptor_set | Command descriptor set. | |
cmd_descriptor | Command field descriptor. | |
cmd_data | Optional payload data. May be NULL if cmd_length == 0. | |
cmd_length | Length of the command payload (parameters). | |
response_descriptor | Descriptor of the response data. May be MIP_INVALID_FIELD_DESCRIPTOR if no response is expected. | |
response_buffer | Buffer 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_inout | As input, the size of response buffer and max response length. As output, returns the actual length of the response data. |
mip_send_callback mip::C::mip_interface_send_function | ( | const mip_interface * | device | ) |
Gets the send function pointer.
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).
device | The mip_interface object. |
data | Data to be sent. |
length | Length of data. |
This is called whenever bytes must be sent to the physical device.
void mip::C::mip_interface_set_recv_function | ( | mip_interface * | device, |
mip_recv_callback | callback | ||
) |
Sets the receive callback function.
device | |
callback | Function which gets data from the device connection. If this is NULL then commands will fail and no data will be received. |
void mip::C::mip_interface_set_send_function | ( | mip_interface * | device, |
mip_send_callback | callback | ||
) |
Sets the send callback function.
device | |
callback | Function which sends raw bytes to the device. This can be NULL if no commands will be issued (they would fail). |
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.
device | |
callback | Update 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. |
void mip::C::mip_interface_set_user_pointer | ( | mip_interface * | device, |
void * | pointer | ||
) |
Sets an optional user data pointer which can be retrieved later.
device | |
pointer |
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.
device | |
packet | A MIP packet containing the command. |
cmd | The command status tracker. Must be valid while the command executes. |
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.
device | |
wait_time | Time 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_cmd | If 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. |
mip_update_callback mip::C::mip_interface_update_function | ( | const mip_interface * | device | ) |
Gets the update function pointer.
void * mip::C::mip_interface_user_pointer | ( | const mip_interface * | device | ) |
Retrieves the pointer set by mip_interface_set_user_pointer().
device |
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.
device | |
cmd |