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, 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 timeout)
	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, uint8_t *parse_buffer, size_t parse_buffer_size, 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, 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 (struct mip_interface *device, mip_timeout wait_time)
	Call to process data from the device. More...
bool	mip::C::mip_interface_default_update (struct mip_interface *device, mip_timeout wait_time)
	Polls the port for new data or command replies. More...
size_t	mip::C::mip_interface_receive_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_process_unparsed_packets (mip_interface *device)
	Process more packets from the internal buffer. More...
bool	mip::C::mip_interface_parse_callback (void *device, const mip_packet_view *packet, mip_timestamp timestamp)
	Wrapper around mip_interface_receive_packet for use with mip_parser. More...
void	mip::C::mip_interface_receive_packet (mip_interface *device, const mip_packet_view *packet, mip_timestamp timestamp)
	Processes a pre-parsed packet for command replies and data. 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...
void	mip::C::mip_interface_set_max_packets_per_update (mip_interface *device, unsigned int max_packets)
	Sets a limit on the number of packets which can be processed in one call to the mip_interface_receive_bytes() function. More...
unsigned int	mip::C::mip_interface_max_packets_per_update (const mip_interface *device)
	Returns the maximum number of packets to parser per update call. 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

High-level C functions for controlling a MIP device.

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

• Sending commands
• Receiving Data

Typedef Documentation

mip_interface

typedef struct mip::C::mip_interface mip::C::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

	device	A pointer to the device interface. Applications can use the user data pointer to access additional information such as the port handle.
	buffer	Buffer to fill with data. Should be allocated before this function is called.
	max_length	Max number of bytes that can be read into the buffer.
	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.
[out]	length_out	Number of bytes actually read into the buffer.
[out]	timestamp_out	Timestamp the data 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).

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.

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

Applications should avoid introducing significant transmission delays as it may cause excessive command response times or timeouts.

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.

Note

The data buffer is almost always a MIP packet. However, there are some cases where this is not true and an application should not rely on it.

See also

mip_interface_send_to_device

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

Parameters

device	The mip_interface object being updated.
timeout	Amount of time to wait for data from the device. This will be zero when checking for data and nonzero when waiting for commands.

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.

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
	)

Polls the port for new data or command replies.

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

Parameters

device
wait_time	Time to wait for data to be received. Passed directly to mip_interface_recv_from_device().

Returns

The value returned by mip_interface_user_recv_from_device.

mip_interface_init()

void mip::C::mip_interface_init	(	mip_interface *	device,
		uint8_t *	parse_buffer,
		size_t	parse_buffer_size,
		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_buffer	A working buffer for the MIP parser. See mip_parser_init().
parse_buffer_size	Size of the parsing buffer. Must be at least MIP_PACKET_LENGTH_MAX.
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_max_packets_per_update()

unsigned int mip::C::mip_interface_max_packets_per_update

(

const mip_interface *

device

)

Returns the maximum number of packets to parser per update call.

mip_interface_parse_callback()

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

Wrapper around mip_interface_receive_packet for use with mip_parser.

Parameters

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

Returns

True

mip_interface_parser()

mip_parser * mip::C::mip_interface_parser

(

mip_interface *

device

)

Returns the MIP parser for the device.

mip_interface_process_unparsed_packets()

void mip::C::mip_interface_process_unparsed_packets

(

mip_interface *

device

)

Process more packets from the internal buffer.

This is an alternative to mip_interface_receive_bytes() for the case when no new input data is available and max_packets is nonzero. The timestamp is reused from the last call to receive_bytes.

This function obeys the max_packets_per_update setting.

Note

Calling this function when max_packets_per_update is zero is unnecessary and has no effect.

mip_interface_receive_bytes()

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

Passes data from the device into the parser.

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.

Returns

The amount of data which couldn't be processed due to the limit on number of packets per parse call. Normally the result is 0.

mip_interface_receive_packet()

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

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

Parameters

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

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,
		size_t *	length_out,
		mip_timestamp *	timestamp_out
	)

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

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

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

void mip::C::mip_interface_set_max_packets_per_update	(	mip_interface *	device,
		unsigned int	max_packets
	)

Sets a limit on the number of packets which can be processed in one call to the mip_interface_receive_bytes() function.

Use this when receiving data in bursts to smooth out the processing load over time.

Note

Make sure the parsing buffer is large enough to hold the data in between receive calls.

Parameters

device
max_packets	Maximum number of packets to parse at once.

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

Sets the send callback function.

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
	)

Sets the update function.

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
	)

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

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

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

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.