Collaboration diagram for Internal message format support:

Files
file	MPSerial.h

file	MPTypes.h

Macros
#define	MP_SERIAL_BUFF 4096
	Default serial buffer allocation size.

#define	MP_SYNC_BYTE1 0x94
	MP Serial synchronisation byte 1. More...

#define	MP_SYNC_BYTE2 0x55
	MP Serial synchronisation byte 2. More...

Typedefs
typedef msg_t	mp_message_t
	Internal representation of SELKIE logger messages. More...

Functions
int	mp_openConnection (const char *port, const int baudRate)
	Set up a connection to the specified port. More...

void	mp_closeConnection (int handle)
	Close existing connection. More...

bool	mp_readMessage (int handle, msg_t *out)
	Static wrapper around mp_readMessage_buf. More...

bool	mp_readMessage_buf (int handle, msg_t out, uint8_t buf[MP_SERIAL_BUFF], int index, int *hw)
	Read data from handle, and parse message if able. More...

bool	mp_packMessage (msgpack_sbuffer sbuf, const msg_t out)
	Pack a message into a buffer. More...

bool	mp_writeMessage (int handle, const msg_t *out)
	Send message to attached device. More...

bool	mp_writeData (int handle, const msg_t *out)
	Send message data (only!) to attached device. More...

void	mp_pack_strarray (msgpack_packer pack, const strarray sa)
	Pack string array. More...

void	mp_pack_numarray (msgpack_packer pack, const size_t entries, const float fa)
	Pack numeric/floating point array. More...

bool	mp_unpack_strarray (strarray sa, msgpack_object_array obj)
	Unpack msgpack array into string array. More...

size_t	mp_unpack_numarray (float *sa, msgpack_object_array obj)
	Allocate array of floats and unpack a msgpack array into it. More...

Detailed Description

Support for internal message pack based data format, including support for serial devices and data files

Macro Definition Documentation

◆ MP_SYNC_BYTE1

#define MP_SYNC_BYTE1 0x94

MP Serial synchronisation byte 1.

0x94 is the MessagePack header for a 4 element array

Definition at line 40 of file MPTypes.h.

◆ MP_SYNC_BYTE2

#define MP_SYNC_BYTE2 0x55

MP Serial synchronisation byte 2.

0x55 (0b01010101) represents 83 as a MessagePack fixed integer.

Definition at line 46 of file MPTypes.h.

Typedef Documentation

◆ mp_message_t

typedef msg_t mp_message_t

Internal representation of SELKIE logger messages.

All messages are MessagePacked arrays with 4 elements. First element is fixed integer 0x55 Second element is a source ID (0-127) Third element is a channel ID (0-127) Fourth element is source specific data, which can be:

A string
A floating point value (single precision)
A millisecond precision timestamp (uint32_t)
An array of strings
An array of bytes

These elements are the same as the members of the msg_t type defined in base/messages.h, with the addition of the initial sync byte.

The use of the initial sync byte and fixed length array provide a two byte signature (0x94 0x55) that can be used to identify message boundaries.

There is no checksumming of transmitted messages under this scheme.

Definition at line 70 of file MPTypes.h.

Function Documentation

◆ mp_closeConnection()

void mp_closeConnection ( int handle )

Close existing connection.

Currently just closes the file descriptor passed as handle

Parameters

[in] handle File descriptor opened with mp_openConnection()

Definition at line 52 of file MPSerial.c.

◆ mp_openConnection()

int mp_openConnection	(	const char *	port,
		const int	baudRate
	)

Set up a connection to the specified port.

Currently just wraps openSerialConnection()

Parameters

[in]	port	Target character device (i.e. Serial port)
[in]	baudRate	Target baud rate

Returns: Return value of openSerialConnection()

Definition at line 43 of file MPSerial.c.

◆ mp_pack_numarray()

void mp_pack_numarray	(	msgpack_packer *	pack,
		const size_t	entries,
		const float *	fa
	)

Pack numeric/floating point array.

Helper function for mp_packMessage()

Packs float array into supplied msgpack_packer object

Parameters

[in]	pack	Pointer to msgpack packer object - must already be initialised
[in]	entries	Number of entries in array
[in]	fa	Pointer to float array to be packed

Definition at line 466 of file MPSerial.c.

◆ mp_pack_strarray()

void mp_pack_strarray	(	msgpack_packer *	pack,
		const strarray *	sa
	)

Pack string array.

Helper function for mp_packMessage()

Packs string array into supplied msgpack_packer object

Parameters

[in]	pack	Pointer to msgpack packer object - must already be initialised
[in]	sa	Pointer to string array to be packed

Definition at line 446 of file MPSerial.c.

◆ mp_packMessage()

bool mp_packMessage	(	msgpack_sbuffer *	sbuf,
		const msg_t *	out
	)

Pack a message into a buffer.

Pack a message into the provided buffer, ready for writing. The buffer is initialised by this function, and destroyed on error.

Caller is responsible for destroying buffer after use

Parameters

[out]	sbuf	msgpack_sbuffer to write into
[in]	out	Message to pack into buffer

Returns: true on success, false on error

Definition at line 330 of file MPSerial.c.

◆ mp_readMessage()

bool mp_readMessage	(	int	handle,
		msg_t *	out
	)

Static wrapper around mp_readMessage_buf.

For single threaded development and testing, uses static variables rather than requiring state to be tracked by caller.

See mp_readMessage_buf() for full description.

Parameters

[in]	handle	File descriptor from mp_openConnection()
[out]	out	Pointer to message structure to fill with data

Returns: True if out now contains a valid message, false otherwise.

Definition at line 66 of file MPSerial.c.

◆ mp_readMessage_buf()

bool mp_readMessage_buf	(	int	handle,
		msg_t *	out,
		uint8_t	buf[MP_SERIAL_BUFF],
		int *	index,
		int *	hw
	)

Read data from handle, and parse message if able.

This function maintains a message buffer (allocated by the caller), filling it from the file handle provided. This handle can be anything supported by read(), but would usually be a file or a serial port.

The index (current search position) and hw (high water / end of valid data) values are also provided by the caller, but will be updated by this function.

If a valid message is found then it is written to the structure provided as a parameter and the function returns true.

If a message cannot be read, the function returns false and the float value field is set to an error value:

0xFF means no message found yet, and more data is required
0xFD is a synonym for 0xFF, but indicates that zero bytes were read from source. This could indicate EOF if reading from file, but can be ignored when streaming from a device.
0xAA means that an error occurred reading in data
0XEE means a valid message header was found, but no valid message

Parameters

[in]	handle	File descriptor from mp_openConnection()
[out]	out	Pointer to message structure to fill with data
[in,out]	buf	Serial data buffer
[in,out]	index	Current search position within `buf`
[in,out]	hw	End of current valid data in `buf`

Returns: True if out now contains a valid message, false otherwise.

Definition at line 101 of file MPSerial.c.

◆ mp_unpack_numarray()

size_t mp_unpack_numarray	(	float **	fa,
		msgpack_object_array *	obj
	)

Allocate array of floats and unpack a msgpack array into it.

Helper function for mp_readMessage_buf()

Unpacks a msgpack_object_array into an array of floats, provided all msgpack_objects are strings.

Parameters

[out]	fa	Pointer to float pointer (will be set to base address of array)
[in]	obj	MessagePacked array

Returns: Number of entries in array, -1 on failure

Definition at line 514 of file MPSerial.c.

◆ mp_unpack_strarray()

bool mp_unpack_strarray	(	strarray *	sa,
		msgpack_object_array *	obj
	)

Unpack msgpack array into string array.

Helper function for mp_readMessage_buf()

Unpacks a msgpack_object_array into a string array, provided all msgpack_objects are strings.

Parameters

[in]	sa	Pointer to string array to be updated
[in]	obj	MessagePacked array

Returns: True on success, False on error

Definition at line 483 of file MPSerial.c.

◆ mp_writeData()

bool mp_writeData	(	int	handle,
		const msg_t *	out
	)

Send message data (only!) to attached device.

Extract message data and writes it (unformatted) to a file descriptor

Parameters

[in]	handle	File descriptor from mp_openConnection()
[in]	out	Pointer to message structure containing data to be extracted.

Returns: True if data successfully written to handle

Definition at line 397 of file MPSerial.c.

◆ mp_writeMessage()

bool mp_writeMessage	(	int	handle,
		const msg_t *	out
	)

Send message to attached device.

Packs message using mp_packMessage and writes it to a file descriptor

Parameters

[in]	handle	File descriptor from mp_openConnection()
[in]	out	Pointer to message structure to be sent.

Returns: True if data successfully written to handle

Definition at line 382 of file MPSerial.c.

Files

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ MP_SYNC_BYTE1

◆ MP_SYNC_BYTE2

Typedef Documentation

◆ mp_message_t

Function Documentation

◆ mp_closeConnection()

◆ mp_openConnection()

◆ mp_pack_numarray()

◆ mp_pack_strarray()

◆ mp_packMessage()

◆ mp_readMessage()

◆ mp_readMessage_buf()

◆ mp_unpack_numarray()

◆ mp_unpack_strarray()

◆ mp_writeData()

◆ mp_writeMessage()