Tiny protocol  0.7.0
Tiny communication protocol for microcontrollers
Functions
Tiny advanced API functions

Functions

void tiny_enable_uid (STinyData *handle, uint8_t on)
 The function enables uid support. Enables uid support. The function affects on tiny_on_rx_byte and on_frame_cb_t behavior. More...
 
int tiny_set_fcs_bits (STinyData *handle, uint8_t bits)
 
int tiny_on_rx_byte (STinyData *handle, uint8_t *pbuf, int len, uint8_t byte)
 The function processes one rx byte. Used in event-based mode. This function processes single received byte. If new frame is completely received, read_cb handler is called and application can take actions on receive frame. Refer to tiny_set_callbacks. More...
 
int tiny_send_start (STinyData *handle, uint8_t flags)
 initiates sending of a new frame More...
 
int tiny_send_buffer (STinyData *handle, uint8_t *pbuf, int len, uint8_t flags)
 sends user provided data in the body of the frame More...
 
int tiny_send_end (STinyData *handle, uint8_t flags)
 completes sending of a new frame More...
 
void tiny_send_terminate (STinyData *handle)
 terminates send operation More...
 
int tiny_read_start (STinyData *handle, uint8_t flags)
 initiates receiving of a new frame More...
 
int tiny_read_buffer (STinyData *handle, uint8_t *pbuf, int len, uint8_t flags)
 reads frame payload to provided buffer More...
 
void tiny_read_terminate (STinyData *handle)
 terminates read operation More...
 
int tiny_lock (STinyData *handle, uint8_t flags)
 locks Tiny state machine for send operations More...
 
void tiny_unlock (STinyData *handle)
 unlock Tiny state machine for send operations More...
 
int tiny_set_callbacks (STinyData *handle, on_frame_cb_t read_cb, on_frame_cb_t send_cb)
 set callbacks for processing frames The function sets callback procs for specified Tiny channel. callbacks will receive all data being sent or received. More...
 
int tiny_get_callbacks (STinyData *handle, on_frame_cb_t *read_cb, on_frame_cb_t *send_cb)
 returns callbacks assigned for frame processing The function returns set callbacks. More...
 
int tiny_get_stat (STinyData *handle, STinyStats *stat)
 
int tiny_clear_stat (STinyData *handle)
 

Detailed Description

Function Documentation

◆ tiny_clear_stat()

int tiny_clear_stat ( STinyData handle)

The function clears Tiny statistics.

Parameters
handle- pointer to Tiny data.
See also
TINY_ERR_INVALID_DATA
TINY_NO_ERROR
Returns
TINY_ERR_INVALID_DATA, TINY_NO_ERROR.
Remarks
This function is not thread safe.

◆ tiny_enable_uid()

void tiny_enable_uid ( STinyData handle,
uint8_t  on 
)

The function enables uid support. Enables uid support. The function affects on tiny_on_rx_byte and on_frame_cb_t behavior.

Parameters
handle- pointer to Tiny structure
on- 0 to disable UID support. 1 to enable UID support.
Remarks
This function is not thread safe.

◆ tiny_get_callbacks()

int tiny_get_callbacks ( STinyData handle,
on_frame_cb_t read_cb,
on_frame_cb_t send_cb 
)

returns callbacks assigned for frame processing The function returns set callbacks.

Parameters
handle- pointer to Tiny data.
read_cb- pointer to store read callback to. can be NULL.
send_cb- pointer to store write callback to. can be NULL.
Returns
TINY_ERR_INVALID_DATA, TINY_NO_ERROR.
Remarks
This function is thread safe.

◆ tiny_get_stat()

int tiny_get_stat ( STinyData handle,
STinyStats stat 
)

The function returns statistics per communication connection.

Parameters
handle- pointer to Tiny data.
stat- pointer of stucture to fill.
See also
TINY_ERR_INVALID_DATA
TINY_NO_ERROR
Returns
TINY_ERR_INVALID_DATA, TINY_NO_ERROR.
Remarks
This function is not thread safe.

◆ tiny_lock()

int tiny_lock ( STinyData handle,
uint8_t  flags 
)

locks Tiny state machine for send operations

This function should be used to perform send operation from parallel threads.

Parameters
handle- pointer to Tiny data
flags- TINY_FLAG_NO_WAIT or TINY_FLAG_WAIT_FOREVER
Returns
TINY_SUCCESS or TINY_ERR_FAILED.
Remarks
This function is thread safe.

◆ tiny_on_rx_byte()

int tiny_on_rx_byte ( STinyData handle,
uint8_t *  pbuf,
int  len,
uint8_t  byte 
)

The function processes one rx byte. Used in event-based mode. This function processes single received byte. If new frame is completely received, read_cb handler is called and application can take actions on receive frame. Refer to tiny_set_callbacks.

Parameters
handle- pointer to Tiny data
pbuf- pointer to a buffer to store bytes being received.
len- maximum size of receiver buffer.
byte- byte received from communication channel.
Returns
TINY_NO_ERROR if byte is processed successfully and more bytes is required. TINY_ERR_OUT_OF_SYNC if sync error occured on communication channel TINY_ERR_DATA_TOO_LARGE TINY_SUCCESS
Remarks
This function may be used in interrupt handlers. This depends on on_frame_cb_t handler set for receive operations, which is implemented by applications.
Warning
to not perform blocking send operations in receive handler if you're using tiny_on_rx_byte in interrupt handler.
Remarks
This function is not thread safe.
See also
on_frame_cb_t
tiny_set_callbacks.

◆ tiny_read_buffer()

int tiny_read_buffer ( STinyData handle,
uint8_t *  pbuf,
int  len,
uint8_t  flags 
)

reads frame payload to provided buffer

The function reads frame payload to provided buffer. Without TINY_FLAG_READ_ALL the function reads no more byte than len, passed to the function. If provided buffer is filled completely, but there are more bytes to read, then the function returns TINY_ERR_DATA_TOO_LARGE (indicating that tiny_read_buffer must be called once again for next portion of bytes). Otherwise, tiny_read_buffer() returns number of bytes contained in the received frame.

If frame payload is too big to fit to provided buffer, but it is required to read whole frame from the communication channel till the end marker, TINY_FLAG_READ_ALL can be specified. In this case, the function will fill provided buffer with frame bytes, and bytes in the end of frame will be lost. The function returns TINY_ERR_DATA_TOO_LARGE, but this means that frame data didn't fit to buffer, and frame is completely received.

If function is in non-blocking mode, it may return immediately with TINY_NO_ERROR. In this case a user should call this function later with the same parameters.

Note
if flags field is set to TINY_FLAG_NO_WAIT, then this function may remember pbuf pointer and return immediately. So, it is responsibility of the caller to make pbuf to be available all the time until block of data is received.
The read data can be considered as valid, only when last buffer is successfully read. That is tiny_read_buffer function returns length of read bytes (>0), or tiny_read_buffer function returns TINY_ERR_DATA_TOO_LARGE if TINY_FLAG_READ_ALL flag is specified.
Parameters
handle- pointer to Tiny data.
pbuf- pointer to buffer to read frame data to.
len- length of the provided buffer in bytes.
flags- TINY_FLAG_NO_WAIT or TINY_FLAG_WAIT_FOREVER, can be combined with TINY_FLAG_READ_ALL
Returns
length in bytes of data received if executed successfully TINY_ERR_AGAIN if non-blocking operation is requested and the channel is busy TINY_ERR_FAILED if writing to the channel failed TINY_ERR_INVALID_DATA if invalid handle is passed TINY_ERR_DATA_TOO_LARGE if all data do not fit in buffer.
See also
TINY_SUCCESS
TINY_ERR_INVALID_DATA
TINY_ERR_FAILED
TINY_ERR_DATA_TOO_LARGE
TINY_FLAG_NO_WAIT
TINY_FLAG_WAIT_FOREVER
TINY_FLAG_READ_ALL
Warning
any failed read operation (tiny_read_buffer), except TINY_ERR_DATA_TOO_LARGE and TINY_ERR_AGAIN case, must be terminated with tiny_read_terminate.
Remarks
This function is not thread safe.

◆ tiny_read_start()

int tiny_read_start ( STinyData handle,
uint8_t  flags 
)

initiates receiving of a new frame

The function initiates receiving of a new frame. It waits for frame start marker in communication channel. If any character different from frame start marker is read from communication channel, it returns TINY_ERR_OUT_OF_SYNC. Just call it once more in this case. If the function is executed successfully, then tiny_read_buffer can be used to read user data from communication channel.

Parameters
handle- pointer to Tiny data.
flags- TINY_FLAG_NO_WAIT, TINY_FLAG_WAIT_FOREVER.
Returns
TINY_SUCCESS if new frame is detected in communication channel. TINY_NO_ERROR if nothing is awaiting in the communication channel and function is in non-blocking mode TINY_ERR_FAILED if writing to the channel failed TINY_ERR_INVALID_DATA if invalid handle is passed TINY_ERR_OUT_OF_SYNC if not valid byte is received
See also
TINY_SUCCESS
TINY_ERR_INVALID_DATA
TINY_NO_ERROR
TINY_ERR_OUT_OF_SYNC
TINY_ERR_FAILED
TINY_FLAG_NO_WAIT
TINY_FLAG_WAIT_FOREVER
Remarks
This function is not thread safe.

◆ tiny_read_terminate()

void tiny_read_terminate ( STinyData handle)

terminates read operation

This function is to be used, when it is required to reset receive state in case of communication error.

Parameters
handle- pointer to Tiny data.
Remarks
This function is not thread safe.

◆ tiny_send_buffer()

int tiny_send_buffer ( STinyData handle,
uint8_t *  pbuf,
int  len,
uint8_t  flags 
)

sends user provided data in the body of the frame

The function sends user provided data (payload) in the body of the frame. It is possible to send several buffers in the single frame. In this case the receiver side will receive all buffers as one data block. Extended read functions allow to read data of the frame to several buffers. If function is in non-blocking mode, it may return immediately with TINY_NO_ERROR. In this case a user should call this function later with the same parameters.

Note
if flags field is set to TINY_FLAG_NO_WAIT, then this function may remember pbuf pointer and return immediately. So, it is responsibility of the caller to make pbuf data to be available all the time until frame is sent.
Parameters
handle- pointer to Tiny data.
pbuf- pointer to buffer with data to send.
len- length of the data to send in bytes.
flags- TINY_FLAG_NO_WAIT or TINY_FLAG_WAIT_FOREVER
Returns
length in bytes of data sent if executed successfully TINY_NO_ERROR if non-blocking operation is requested and the channel is busy TINY_ERR_FAILED if writing to the channel failed TINY_ERR_INVALID_DATA if invalid handle is passed
See also
TINY_SUCCESS
TINY_ERR_INVALID_DATA
TINY_ERR_TIMEOUT
TINY_ERR_FAILED
TINY_FLAG_NO_WAIT
TINY_FLAG_WAIT_FOREVER
Warning
any failed send operation (tiny_send_buffer, tiny_send_end), except timeout cases, must be terminated with tiny_send_terminate, otherwise the thread can be blocked.
Remarks
This function is not thread safe.

◆ tiny_send_end()

int tiny_send_end ( STinyData handle,
uint8_t  flags 
)

completes sending of a new frame

The function completes sending of a new frame by writing FCS block and frame end marker to communication channel. If the function is executed successfully, then tiny_send_start can be executed again.

Parameters
handle- pointer to Tiny data.
flags- TINY_FLAG_NO_WAIT or TINY_FLAG_WAIT_FOREVER
Returns
TINY_SUCCESS if send frame is completed successfully. TINY_NO_ERROR if non-blocking operation is requested and the channel is busy TINY_ERR_FAILED if writing to the channel failed TINY_ERR_INVALID_DATA if invalid handle is passed
See also
TINY_SUCCESS
TINY_NO_ERROR
TINY_ERR_INVALID_DATA
TINY_ERR_TIMEOUT
TINY_ERR_FAILED
TINY_FLAG_NO_WAIT
TINY_FLAG_WAIT_FOREVER
Remarks
This function is not thread safe.

Returns TINY_SUCCESS if frame sent is competed negative value in case of error

◆ tiny_send_start()

int tiny_send_start ( STinyData handle,
uint8_t  flags 
)

initiates sending of a new frame

The function initiates sending of a new frame by writing frame start marker to communication channel. If the function is executed successfully, then tiny_send_buffer and tiny_send_end can be used to pass the data. If platform supports mutexes, the function locks internal mutex automatically.

Parameters
handle- pointer to Tiny data.
flags- TINY_FLAG_NO_WAIT or TINY_FLAG_WAIT_FOREVER
Returns
TINY_SUCCESS if new frame transmission is started successfully TINY_ERR_TIMEOUT if non-blocking operation is requested and the channel is busy TINY_ERR_FAILED if writing to the channel failed TINY_ERR_INVALID_DATA if invalid handle is passed
See also
TINY_SUCCESS
TINY_ERR_INVALID_DATA
TINY_ERR_TIMEOUT
TINY_ERR_FAILED
TINY_FLAG_NO_WAIT
TINY_FLAG_WAIT_FOREVER
tiny_lock
tiny_unlock
Remarks
This function is thread safe.

◆ tiny_send_terminate()

void tiny_send_terminate ( STinyData handle)

terminates send operation

This function is to be used, when it is required to reset send state in case of communication error

Parameters
handle- pointer to Tiny data.

◆ tiny_set_callbacks()

int tiny_set_callbacks ( STinyData handle,
on_frame_cb_t  read_cb,
on_frame_cb_t  send_cb 
)

set callbacks for processing frames The function sets callback procs for specified Tiny channel. callbacks will receive all data being sent or received.

Parameters
handle- pointer to Tiny data.
read_cb- pointer to callback function.
send_cb- pointer to callback function.
Returns
TINY_ERR_INVALID_DATA, TINY_NO_ERROR.
Remarks
This function is thread safe.

◆ tiny_set_fcs_bits()

int tiny_set_fcs_bits ( STinyData handle,
uint8_t  bits 
)

The function sets number of bits used for fcs

Parameters
handle- pointer to Tiny structure
bits- number of bits to use for fcs: 16 or 32.
Returns
TINY_ERR_FAILED TINY_NO_ERROR
Remarks
This function is not thread safe.

◆ tiny_unlock()

void tiny_unlock ( STinyData handle)

unlock Tiny state machine for send operations

This function should be used to perform send operation from parallel threads to unlock parallel threads.

Parameters
handle- pointer to Tiny data.
Remarks
This function is thread safe.