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

Collaboration diagram for Mip Interface [C]:

Classes
struct	mip_interface
	State of the interface for communicating with a MIP device. More...

Typedefs
typedef struct mip_interface	mip_interface
	State of the interface for communicating with a MIP device. More...

typedef bool(*	mip_recv_callback) (struct mip_interface device, uint8_t buffer, size_t max_length, timeout_type wait_time, size_t out_length, timestamp_type timestamp_out)
	Receives new data from the device. More...

typedef bool(*	mip_send_callback) (struct mip_interface device, const uint8_t data, size_t length)
	Sends data to the port (i.e. More...

typedef bool(*	mip_update_callback) (struct mip_interface *device, timeout_type timeout)
	Callback function typedef for custom update behavior. More...

Functions
mip_cmd_queue *	mip_interface_cmd_queue (mip_interface *device)
	Returns the commmand queue for the device. More...

bool	mip_interface_default_update (mip_interface *device, timeout_type wait_time)
	Polls the port for new data or command replies. More...

void	mip_interface_init (mip_interface device, uint8_t parse_buffer, size_t parse_buffer_size, timeout_type parse_timeout, timeout_type base_reply_timeout, mip_send_callback send, mip_recv_callback recv, mip_update_callback update, void *user_pointer)
	Initialize the mip_interface components. More...

unsigned int	mip_interface_max_packets_per_update (const mip_interface *device)
	Returns the maximum number of packets to parser per update call. More...

bool	mip_interface_parse_callback (void device, const mip_packet packet, timestamp_type timestamp)
	Wrapper around mip_interface_receive_packet for use with mip_parser. More...

mip_parser *	mip_interface_parser (mip_interface *device)
	Returns the MIP parser for the device. More...

void	mip_interface_process_unparsed_packets (mip_interface *device)
	Process more packets from the internal buffer. More...

remaining_count	mip_interface_receive_bytes (mip_interface device, const uint8_t data, size_t length, timestamp_type timestamp)
	Passes data from the device into the parser. More...

void	mip_interface_receive_packet (mip_interface device, const mip_packet packet, timestamp_type timestamp)
	Processes a pre-parsed packet for command replies and data. More...

bool	mip_interface_recv_from_device (mip_interface device, uint8_t buffer, size_t max_length, timeout_type timeout, size_t length_out, timestamp_type now)
	Checks for data at the port and reads it into buffer. More...

mip_recv_callback	mip_interface_recv_function (const mip_interface *device)
	Gets the receive function pointer. More...

void	mip_interface_register_extractor (mip_interface device, mip_dispatch_handler handler, uint8_t descriptor_set, uint8_t field_descriptor, mip_dispatch_extractor callback, void *field_ptr)
	Registers a callback for packets of the specified descriptor set. More...

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

enum mip_cmd_result	mip_interface_run_command (mip_interface device, uint8_t descriptor_set, uint8_t field_descriptor, const uint8_t payload, uint8_t payload_length)
	Runs a command using a pre-serialized payload. More...

enum mip_cmd_result	mip_interface_run_command_packet (mip_interface device, const mip_packet packet, mip_pending_cmd *cmd)
	Similar to mip_interface_start_command_packet but waits for the command to complete. More...

enum mip_cmd_result	mip_interface_run_command_with_response (mip_interface device, uint8_t descriptor_set, uint8_t field_descriptor, const uint8_t payload, uint8_t payload_length, uint8_t response_descriptor, uint8_t response_data, uint8_t response_length_inout)
	Runs a command using a pre-serialized payload. More...

mip_send_callback	mip_interface_send_function (const mip_interface *device)
	Gets the send function pointer. More...

bool	mip_interface_send_to_device (mip_interface device, const uint8_t data, size_t length)
	Sends data to the port (i.e. More...

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

void	mip_interface_set_recv_function (mip_interface *device, mip_recv_callback function)
	Sets the receive callback function. More...

void	mip_interface_set_send_function (mip_interface *device, mip_send_callback function)
	Sets the send callback function. More...

void	mip_interface_set_update_function (mip_interface *device, mip_update_callback function)
	Sets the update function. More...

void	mip_interface_set_user_pointer (mip_interface device, void pointer)
	Sets an optional user data pointer which can be retrieved later. More...

bool	mip_interface_start_command_packet (mip_interface device, const mip_packet packet, mip_pending_cmd *cmd)
	Queues the command and sends the packet. More...

bool	mip_interface_update (mip_interface *device, timeout_type wait_time)
	Call to process data from the device. More...

mip_update_callback	mip_interface_update_function (const mip_interface *device)
	Gets the update function pointer. More...

void *	mip_interface_user_pointer (const mip_interface *device)
	Retrieves the pointer set by mip_interface_set_user_pointer(). More...

enum mip_cmd_result	mip_interface_wait_for_reply (mip_interface device, mip_pending_cmd cmd)
	Blocks until the pending command completes or times out. 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_interface mip_interface

State of the interface for communicating with a MIP device.

◆ mip_recv_callback

mip_recv_callback

Receives new data from the device.

Called repeatedly by mip_interface_update() while waiting for command responses.

Parameters

device	The mip interface object
buffer	Buffer to fill with data. Should be allocated before calling this function
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	Number of bytes actually read into the buffer.
timestamp_out	Timestamp of 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.

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.

Definition at line 37 of file mip_interface.h.

◆ mip_send_callback

mip_send_callback

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.

Note: There are cases where the data will not be a MIP packet.

Definition at line 36 of file mip_interface.h.

◆ mip_update_callback

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.

Definition at line 38 of file mip_interface.h.

Function Documentation

◆ mip_interface_cmd_queue()

mip_cmd_queue* mip_interface_cmd_queue ( mip_interface * device )

Returns the commmand queue for the device.

Definition at line 270 of file mip_interface.c.

◆ mip_interface_default_update()

bool mip_interface_default_update	(	struct mip_interface *	device,
		timeout_type	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.

Definition at line 363 of file mip_interface.c.

◆ mip_interface_init()

void mip_interface_init	(	mip_interface *	device,
		uint8_t *	parse_buffer,
		size_t	parse_buffer_size,
		timeout_type	parse_timeout,
		timeout_type	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().

Definition at line 92 of file mip_interface.c.

◆ mip_interface_max_packets_per_update()

unsigned int mip_interface_max_packets_per_update ( const mip_interface * device )

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

Definition at line 233 of file mip_interface.c.

◆ mip_interface_parse_callback()

bool mip_interface_parse_callback	(	void *	device,
		const mip_packet *	packet,
		timestamp_type	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

Definition at line 448 of file mip_interface.c.

◆ mip_interface_parser()

mip_parser* mip_interface_parser ( mip_interface * device )

Returns the MIP parser for the device.

Definition at line 262 of file mip_interface.c.

◆ mip_interface_process_unparsed_packets()

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

Definition at line 418 of file mip_interface.c.

◆ mip_interface_receive_bytes()

remaining_count mip_interface_receive_bytes	(	mip_interface *	device,
		const uint8_t *	data,
		size_t	length,
		timestamp_type	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.

Definition at line 401 of file mip_interface.c.

◆ mip_interface_receive_packet()

void mip_interface_receive_packet	(	mip_interface *	device,
		const mip_packet *	packet,
		timestamp_type	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.

Definition at line 433 of file mip_interface.c.

◆ mip_interface_recv_from_device()

bool mip_interface_recv_from_device	(	mip_interface *	device,
		uint8_t *	buffer,
		size_t	max_length,
		timeout_type	wait_time,
		size_t *	length_out,
		timestamp_type *	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).

Definition at line 315 of file mip_interface.c.

◆ mip_interface_recv_function()

mip_recv_callback mip_interface_recv_function ( const mip_interface * device )

Gets the receive function pointer.

Parameters

device

Returns: The receive callback function. May be NULL.

Definition at line 167 of file mip_interface.c.

◆ mip_interface_register_extractor()

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

Definition at line 655 of file mip_interface.c.

◆ mip_interface_register_field_callback()

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

Definition at line 633 of file mip_interface.c.

◆ mip_interface_register_packet_callback()

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

Definition at line 610 of file mip_interface.c.

◆ mip_interface_run_command()

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

Definition at line 515 of file mip_interface.c.

◆ mip_interface_run_command_packet()

enum mip_cmd_result mip_interface_run_command_packet	(	mip_interface *	device,
		const mip_packet *	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.

Definition at line 562 of file mip_interface.c.

◆ mip_interface_run_command_with_response()

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

Returns: mip_cmd_result MIP_ACK_OK - Command completed successfully. MIP_NACK_* - Device rejected the command. MIP_STATUS_* - An error occured (e.g. timeout).

Parameters

response_descriptor Descriptor of the response data. May be MIP_INVALID_FIELD_DESCRIPTOR if no response is expected.

Definition at line 527 of file mip_interface.c.

◆ mip_interface_send_function()

mip_send_callback mip_interface_send_function ( const mip_interface * device )

Gets the send function pointer.

Parameters

device

Returns: The send callback function. May be NULL.

Definition at line 140 of file mip_interface.c.

◆ mip_interface_send_to_device()

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

Definition at line 296 of file mip_interface.c.

◆ mip_interface_set_max_packets_per_update()

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

Definition at line 253 of file mip_interface.c.

◆ mip_interface_set_recv_function()

void mip_interface_set_recv_function	(	mip_interface *	device,
		mip_recv_callback	callback
	)

Sets the receive callback function.

Parameters

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

Definition at line 155 of file mip_interface.c.

◆ mip_interface_set_send_function()

void mip_interface_set_send_function	(	mip_interface *	device,
		mip_send_callback	callback
	)

Sets the send callback function.

Parameters

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

Definition at line 128 of file mip_interface.c.

◆ mip_interface_set_update_function()

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

Definition at line 188 of file mip_interface.c.

◆ mip_interface_set_user_pointer()

void mip_interface_set_user_pointer	(	mip_interface *	device,
		void *	pointer
	)

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

Parameters

device
pointer

Definition at line 212 of file mip_interface.c.

◆ mip_interface_start_command_packet()

bool mip_interface_start_command_packet	(	mip_interface *	device,
		const mip_packet *	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.

Definition at line 583 of file mip_interface.c.

◆ mip_interface_update()

bool mip_interface_update	(	struct mip_interface *	device,
		timeout_type	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).

Definition at line 340 of file mip_interface.c.

◆ mip_interface_update_function()

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

Definition at line 200 of file mip_interface.c.

◆ mip_interface_user_pointer()

void* mip_interface_user_pointer ( const mip_interface * device )

Retrieves the pointer set by mip_interface_set_user_pointer().

Parameters

device

Returns: The pointer value.

Definition at line 224 of file mip_interface.c.

◆ mip_interface_wait_for_reply()

enum mip_cmd_result 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.

Definition at line 471 of file mip_interface.c.

Classes

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ mip_interface

◆ mip_recv_callback

◆ mip_send_callback

◆ mip_update_callback

Function Documentation

◆ mip_interface_cmd_queue()

◆ mip_interface_default_update()

◆ mip_interface_init()

◆ mip_interface_max_packets_per_update()

◆ mip_interface_parse_callback()

◆ mip_interface_parser()

◆ mip_interface_process_unparsed_packets()

◆ mip_interface_receive_bytes()

◆ mip_interface_receive_packet()

◆ mip_interface_recv_from_device()

◆ mip_interface_recv_function()

◆ mip_interface_register_extractor()

◆ mip_interface_register_field_callback()

◆ mip_interface_register_packet_callback()

◆ mip_interface_run_command()

◆ mip_interface_run_command_packet()

◆ mip_interface_run_command_with_response()

◆ mip_interface_send_function()

◆ mip_interface_send_to_device()

◆ mip_interface_set_max_packets_per_update()

◆ mip_interface_set_recv_function()

◆ mip_interface_set_send_function()

◆ mip_interface_set_update_function()

◆ mip_interface_set_user_pointer()

◆ mip_interface_start_command_packet()

◆ mip_interface_update()

◆ mip_interface_update_function()

◆ mip_interface_user_pointer()

◆ mip_interface_wait_for_reply()