mip_interface.c File Reference

#include "mip_interface.h"
#include "mip_field.h"
#include "definitions/descriptors.h"
#include <assert.h>
#include <stdio.h>

Include dependency graph for mip_interface.c:

Functions
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...
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)
	Initialize the mip_interface components. More...
void	mip_interface_set_update_function (struct mip_interface *device, mip_update_callback function)
	Sets the update function. More...
mip_update_callback	mip_interface_update_function (struct mip_interface *device)
	Gets the update function pointer. More...
void	mip_interface_set_user_pointer (mip_interface *device, void *pointer)
	Sets an optional user data pointer which can be retrieved later. More...
void *	mip_interface_user_pointer (const mip_interface *device)
	Retrieves the pointer set by mip_interface_set_user_pointer(). 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...
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...
bool	mip_interface_update (struct mip_interface *device, bool blocking)
	Call to process data from the device. More...
bool	mip_interface_default_update (struct mip_interface *device, bool blocking)
	Polls the port for new data or command replies. More...
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). More...
remaining_count	mip_interface_receive_bytes (mip_interface *device, const uint8_t *data, size_t length, timestamp_type timestamp)
	Receive data from the port (i.e. the physical device) into the parser. More...
void	mip_interface_process_unparsed_packets (mip_interface *device)
	Process more packets from the internal buffer. 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...
mip_parser *	mip_interface_parser (mip_interface *device)
	Returns the MIP parser for the device. More...
mip_cmd_queue *	mip_interface_cmd_queue (mip_interface *device)
	Returns the commmand queue for the device. More...
enum mip_cmd_result	mip_interface_wait_for_reply (mip_interface *device, const mip_pending_cmd *cmd)
	Blocks until the pending command completes or times out. More...
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. More...
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. 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...
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. 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...
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_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...

Function Documentation

mip_interface_cmd_queue()

mip_cmd_queue* mip_interface_cmd_queue

(

mip_interface *

device

)

Returns the commmand queue for the device.

mip_interface_default_update()

bool mip_interface_default_update	(	struct mip_interface *	device,
		bool	blocking
	)

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	The mip_interface object.
blocking	Ignored.

Returns

The value returned by mip_interface_user_recv_from_device.

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
	)

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

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.

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

mip_interface_parser()

mip_parser* mip_interface_parser

(

mip_interface *

device

)

Returns the MIP parser for the device.

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.

mip_interface_receive_bytes()

remaining_count mip_interface_receive_bytes	(	mip_interface *	device,
		const uint8_t *	data,
		size_t	length,
		timestamp_type	timestamp
	)

Receive data from the port (i.e. the physical 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_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.

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.

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.

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.

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

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.

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.

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

void mip_interface_set_update_function	(	struct mip_interface *	device,
		mip_update_callback	function
	)

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.

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

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.

mip_interface_update()

bool mip_interface_update	(	struct mip_interface *	device,
		bool	blocking
	)

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
blocking	This is true when called from within a blocking command function. Applications should generally set this to false, e.g. when calling this to process incoming data packets.

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_interface_update_function

(

struct 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_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_interface_wait_for_reply	(	mip_interface *	device,
		const mip_pending_cmd *	cmd
	)

Blocks until the pending command completes or times out.

Parameters

device
cmd

Returns

The final status of the command.