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, uint8_t *buffer, size_t max_length, mip_timeout wait_time, bool from_cmd, size_t *length_out, 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, uint8_t *buffer, size_t max_length, mip_timeout wait_time, bool from_cmd, size_t *length_out, mip_timestamp *timestamp_out)
	Checks for data at the port and reads it into buffer. More...
bool	mip::C::mip_interface_update (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 (mip_interface *device, mip_timeout wait_time, bool from_cmd)
	Polls the port for new data or command replies. More...
bool	mip::C::mip_interface_default_update_ext_buffer (mip_interface *device, mip_timeout wait_time, bool from_cmd, uint8_t *buffer, size_t buffer_size)
	Polls the port for new data or command replies using a supplied buffer. More...
void	mip::C::mip_interface_input_bytes_andor_time (mip_interface *device, const uint8_t *received_data, size_t data_length, mip_timestamp now)
	This function takes care of processing received data and updating the current time. More...
void	mip::C::mip_interface_input_bytes_from_device (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_from_device (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_update_time (mip_interface *device, mip_timestamp timestamp)
	Call this to ensure that pending commands time out properly. More...
bool	mip::C::mip_interface_parse_callback (void *device, const mip_packet_view *packet, mip_timestamp timestamp)
	Wrapper around mip_interface_input_packet_from_device 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...

Detailed Description

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

• Sending commands
• Receiving Data

Typedef Documentation

mip_send_callback

mip::C::mip_send_callback

Parameters

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.

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_recv_callback

mip::C::mip_recv_callback

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

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.

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_update_callback

mip::C::mip_update_callback

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_from_device(). Many applications can set this callback to mip_interface_default_update().

Parameters

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.

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.

mip_interface

typedef struct mip::C::mip_interface mip::C::mip_interface

Function Documentation

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
	)

Parameters

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.

mip_interface_send_to_device()

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

Parameters

device	The mip_interface object.
data	Data to be sent.
length	Length 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_recv_from_device()

bool mip::C::mip_interface_recv_from_device	(	mip_interface *	device,
		uint8_t *	buffer,
		size_t	max_length,
		mip_timeout	wait_time,
		bool	from_cmd,
		size_t *	length_out,
		mip_timestamp *	timestamp_out
	)

Parameters

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.

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

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

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_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.

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

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

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

Warning

This function is provided for convenience and quick setup. It will work for most applications, but it is not optimized for your application. It may be unsuitable for some situations such as small microcontrollers (due to the fixed-size stack-allocated data buffer) or in combination with multi-threading.

Parameters

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.

Returns

The value returned by mip_interface_user_recv_from_device.

mip_interface_default_update_ext_buffer()

bool mip::C::mip_interface_default_update_ext_buffer	(	mip_interface *	device,
		mip_timeout	wait_time,
		bool	from_cmd,
		uint8_t *	buffer,
		size_t	buffer_size
	)

This function is suitable for most single-threaded use cases where performance is not critical. In performance-sensitive applications, it's best to either read directly into the mip parser buffer, or call mip_interface_input_bytes from your own update function (bypassing mip_interface_recv_from_device entirely).

Parameters

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.
buffer	Buffer to hold data read from the device connection. At least 512 bytes are recommended for better performance, with a few kB being the point of diminishing return.
buffer_size	Size of the buffer.

Returns

The value returned by mip_interface_user_recv_from_device.

mip_interface_input_bytes_andor_time()

void mip::C::mip_interface_input_bytes_andor_time	(	mip_interface *	device,
		const uint8_t *	received_data,
		size_t	data_length,
		mip_timestamp	now
	)

User-defined update functions should either call this function after getting data from the connection, or do the equivalent manually:

• Input bytes to the parser, via mip_interface_input_bytes_from_device, and
• Update the current time via mip_interface_update_time

mip_interface_input_bytes_from_device()

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

Parameters

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.

mip_interface_input_packet_from_device()

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

Parameters

device
packet	The received MIP packet.
timestamp	Timestamp of the received MIP packet.

mip_interface_update_time()

void mip::C::mip_interface_update_time	(	mip_interface *	device,
		mip_timestamp	timestamp
	)

This function should be called regularly (i.e. from within the update callback). Otherwise, unacknowledged commands may never time out. This can happen even if data is being sent through mip_interface_input_bytes_from_device because the device may be streaming data. See the implementation of mip_interface_default_update for an example.

param device param timestamp Current time, as if timestamping received data.

mip_interface_parse_callback()

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

Parameters

device	Void pointer to the device. Must be a mip_interface pointer.
packet	MIP Packet from the parser.
timestamp	Timestamp of the packet.

Returns

true

mip_interface_wait_for_reply()

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

Parameters

device
cmd

Returns

The final status of the command.

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
	)

Parameters

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

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_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
	)

Parameters

	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.

Returns

mip_cmd_result

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
	)

Parameters

device
packet	A MIP packet containing the command.
cmd	The command status tracker. No lifetime requirement.

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
	)

Parameters

device
packet	A MIP packet containing the command.
cmd	The 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_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
	)

Parameters

device
handler	An 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_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
	)

Parameters

device
handler	An 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_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
	)

Parameters

device
handler	An 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_set_recv_function()

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

Parameters

device
callback	Function 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
	)

Parameters

device
callback	Function 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
	)

By default, the update function is mip_interface_default_update.

See also

mip_update_callback

mip_interface_update

Parameters

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.

mip_interface_set_user_pointer()

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

Parameters

device
pointer

mip_interface_recv_function()

mip_recv_callback mip::C::mip_interface_recv_function

(

const mip_interface *

device

)

Parameters

device

Returns

The receive callback function. May be NULL.

mip_interface_send_function()

mip_send_callback mip::C::mip_interface_send_function

(

const mip_interface *

device

)

Parameters

device

Returns

The send callback function. May be NULL.

mip_interface_update_function()

mip_update_callback mip::C::mip_interface_update_function

(

const mip_interface *

device

)

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

)

Parameters

device

Returns

The pointer value.

mip_interface_parser()

mip_parser * mip::C::mip_interface_parser

(

mip_interface *

device

)

mip_interface_cmd_queue()

mip_cmd_queue * mip::C::mip_interface_cmd_queue

(

mip_interface *

device

)