Sonochan II 0.1

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Data Structures | Macros | Enumerations | Functions
uniprot.h File Reference

Universal protocol driver. More...

`#include "device_generic_hid.h"`
`#include <inttypes.h>`

Go to the source code of this file.

## Data Structures
struct | UNI_PACKET_STATE_t
| Structure which can hold data and command state. More...
struct | UNI_PACKET_CONFIG_t
| Configuration structure for RX and TX packet. More...
struct | UNI_SR_flags
| Status register flags. More...
union | UNI_SR_t
| Status register. More...

## Macros
#define | UNI_CHAR_HEADER 'H'
| Character, which will be used as first Byte in header of packet. More...
#define | UNI_CHAR_DATA 'D'
| Character, which will be used as first Byte in "data" section of packet. More...
#define | UNI_CHAR_TAIL 'T'
| Character, which will be used as first Byte in tail of packet. More...
#define | UNI_CHAR_ACK 'A'
| Character, which will be used as ACK. More...
#define | UNI_CHAR_NACK 'N'
| Character, which will be used as NACK. More...
#define | UNI_CHAR_RESET 'R'
| Character, which will be used as RESET (reset just protocol, not HW) More...
#define | UNI_CHAR_BUFFER_OVERFLOW 'O'
| Character, which will be used as RX buffer overflow. More...
#define | UNI_MAX_PIPE 0

## Enumerations
enum | UNI_RES_CODE { UNI_SUCCESS = 0, UNI_FAIL = 2, UNI_INVALID_PARAMETER = 3, UNI_TX_PACKET_NOT_CONFIGURED = 4 }
| Error codes returned by functions. More...
enum | UNI_PACKET_STATE_DATA { UNI_STATE_HEADER_H = 7, UNI_STATE_HEADER_NOB_H = 8, UNI_STATE_HEADER_NOB_L = 9, UNI_STATE_DATA_D = 10, UNI_STATE_DATA = 11, UNI_STATE_TAIL_T = 12, UNI_STATE_CRC16_H = 13, UNI_STATE_CRC16_L = 14 }
| Enumeration of possible data packet states (header, data, tail) More...
enum | UNI_PACKET_STATE_CMD { UNI_STATE_CMD_CHAR = 0, UNI_STATE_CMD_CRC16_H = 1, UNI_STATE_CMD_CRC16_L = 2 }
| Enumeration of possible command packet frames. More...

## Functions
void | Uniprot_Init (void)
| Configures the board hardware and chip peripherals. Automatic enable global interrupt! More...
void | Uniprot_Task (void)
| This task handle in and out data stream. More...
UNI_RES_CODE | Uniprot_config_RX_packet (uint8_t i_pipe_ID, uint16_t i_rx_max_num_of_data_Bytes, void *p_rx_buffer)
| Configure RX packet on defined pipe. More...
UNI_RES_CODE | Uniprot_config_TX_packet (uint8_t i_pipe_ID, uint16_t i_tx_num_of_data_Bytes, void *p_tx_buffer)
| Configure TX packet on defined pipe. More...
UNI_RES_CODE | Uniprot_Is_RX_pipe_ready (uint8_t i_pipe_ID)
| Test if RX pipe is ready to receive new data. More...
UNI_RES_CODE | Uniprot_Is_TX_pipe_ready (uint8_t i_pipe_ID)
| Test if TX pipe is ready transmit new data. More...
UNI_RES_CODE | Uniprot_Is_TX_transmission_enable (uint8_t i_pipe_ID)
| Test if all uniprot low level data are ready to send. More...
void | Uniprot_rx_data (uint8_t i_pipe_ID, uint8_t *p_DataArray)
| This function is called when data came from driver. More...
void | Uniprot_tx_data (uint8_t i_pipe_ID, uint8_t *p_DataArray)
| This function is called when driver (and uniprot) is ready to send data. More...
UNI_RES_CODE | Uniprot_Is_reinit_flag_set (uint8_t i_pipe_ID)
| Check if reinitialize flag is set. More...
UNI_RES_CODE | Uniprot_Set_init_reinit_flag (uint8_t i_pipe_ID)
| Set initialize/reinitialize flag. More...

## Detailed Description

Universal protocol driver.

1. Set pipes: open uniprot.h file. Find "Configuration" paragraph. Configure pipe by following comment. However this settings can be also defined in driver header file, but it is not rule.
2. Go to "Includes" paragraph. Here include low level driver header files. Please note, that low level driver SHOULD support uniprot. If driver does NOT SUPPORT uniprot, just modify it. On line where driver received data call function Uniprot_rx_data(). On line when transmitter is ready send data check uniprot TX ready - function Uniprot_Is_TX_transmission_enable(). If function return 1 (exactly 1, if there is different number than 0 or 1 there is error!) then can be called function Uniprot_tx_data(). That is it!
3. Configure RX. This step is necessary only when you want use receiver. Just call function Uniprot_config_RX_packet()
4. Check if RX is complete. Again, only if you use receiver. Call function Uniprot_Is_RX_pipe_ready()
5. Configure TX. This step is necessary only when you want use transmitter. Call function Uniprot_config_TX_packet()
6. Check if TX is complete. Again, only if you use transmitter. Call function Uniprot_Is_TX_pipe_ready()

7. If there is no communication problem, everything should work as expected. But.... there always can be problem (bad connection, lazy operating system, wizard....), so for these cases is there more functions. In case, that uniprot can not synchronize data stream (too high BER) then is set REINIT flag. That means hardware driver and uniprot was reset. Obviously uniprot can not know what higher layers do with data, so higher layers should check if reset occur. This can be done by function Uniprot_Is_reinit_flag_set(). Function return 0 if reset not occur. When occur, then return 1. If there is some else problem return different error code. So when reset occurs that means higher layer should send all not confirmed data again. Please remember when reset occurs, then all data in RX and TX buffers are invalid! Pipe RX and TX packets MUST be configured again!

   Created 24.09.2013 Modified 02.04.2014

Version
  0.3

Author
  Martin Stejskal

## Macro Definition Documentation

#define UNI_CHAR_ACK 'A'

Character, which will be used as ACK.

#define UNI_CHAR_BUFFER_OVERFLOW 'O'

Character, which will be used as RX buffer overflow.

#define UNI_CHAR_DATA 'D'

Character, which will be used as first Byte in "data" section of packet.

#define UNI_CHAR_HEADER 'H'

Character, which will be used as first Byte in header of packet.

#define UNI_CHAR_NACK 'N'

Character, which will be used as NACK.

#define UNI_CHAR_RESET 'R'

Character, which will be used as RESET (reset just protocol, not HW)

#define UNI_CHAR_TAIL 'T'

Character, which will be used as first Byte in tail of packet.

#define UNI_MAX_PIPE 0

## Enumeration Type Documentation

enum UNI_PACKET_STATE_CMD

Enumeration of possible command packet frames.

Because there is possibility that interface device will support only 8bit
communication, all states must be divided into 8bit values

Enumerator
UNI_STATE_CMD_CHAR | CMD_CHAR Command character.
UNI_STATE_CMD_CRC16_H | CRC16_H CRC - High 8 bits.
UNI_STATE_CMD_CRC16_L | CRC16_L CRC - Low 8 bits.

enum UNI_PACKET_STATE_DATA

Enumeration of possible data packet states (header, data, tail)

Because there is possibility that interface device will support only 8bit
communication, all states must be divided into 8bit values.

Note
  Numbers are intent start from 7 to avoid miss when programmer try set cmd state by data state value.

Enumerator
UNI_STATE_HEADER_H | UNI_STATE_HEADER_H Header.
UNI_STATE_HEADER_NOB_H | UNI_STATE_HEADER_NOB_H Number of Bytes.
UNI_STATE_HEADER_NOB_L | UNI_STATE_HEADER_NOB_L Number of bytes.
UNI_STATE_DATA_D | UNI_STATE_DATA_D Data introduction.
UNI_STATE_DATA | UNI_STATE_DATA Data.
UNI_STATE_TAIL_T | UNI_STATE_TAIL_T Tail.
UNI_STATE_CRC16_H | UNI_STATE_CRC16_H CRC - High 8 bits.
UNI_STATE_CRC16_L | UNI_STATE_CRC16_L CRC - Low 8 bits.

enum UNI_RES_CODE

Error codes returned by functions.

Enumerator
UNI_SUCCESS | UNI_SUCCESS.
UNI_FAIL | UNI_FAIL.
UNI_INVALID_PARAMETER | UNI_INVALID_PARAMETER.
UNI_TX_PACKET_NOT_CONFIGURED | UNI_TX_PACKET_NOT_CONFIGURED.

## Function Documentation

UNI_RES_CODE Uniprot_config_RX_packet | ( | uint8_t | i_pipe_ID,
|  | uint16_t | i_rx_max_num_of_data_Bytes,
|  | void * | p_rx_buffer
| ) |  |
| inline

Configure RX packet on defined pipe.

When this function is called, that means that rx_buffer will be
overwritten!

Parameters

  i_pipe_ID | ID number of pipe. Must not be higher than UNI_MAX_PIPE
  p_rx_buffer | Pointer to RX buffer (store data here)
  i_rx_max_num_of_data_Bytes | Define maximum received Bytes. Also define maximum used size of rx_buffer in Bytes

Returns
  UNI_SUCCESS if all right

UNI_RES_CODE Uniprot_config_TX_packet | ( | uint8_t | i_pipe_ID,
|  | uint16_t | i_tx_num_of_data_Bytes,
|  | void * | p_tx_buffer
| ) |  |
| inline

Configure TX packet on defined pipe.

When called this function data transmitting start!

Parameters

  i_pipe_ID | ID number of pipe. Must not be higher than UNI_MAX_PIPE
  i_tx_num_of_data_Bytes | Number of data Bytes, which driver should expect
  p_tx_buffer | Pointer to TX buffer (load data from here)

Returns
  UNI_SUCCESS if all right

void Uniprot_Init | ( | void | ) |  |

Configures the board hardware and chip peripherals. Automatic enable global interrupt!

UNI_RES_CODE Uniprot_Is_reinit_flag_set | ( | uint8_t | i_pipe_ID) |  |
| inline

Check if reinitialize flag is set.

When flag is set, then return true (1) and clear flag. Also do routines
needed to uniprot.

Parameters

  i_pipe_ID | Pipe ID (number of used pipe)

Returns
  True if flag is set (1). Else false (0). If i_pipe_ID is invalid,
  then return UNI_INVALID_PARAMETER (2)

UNI_RES_CODE Uniprot_Is_RX_pipe_ready | ( | uint8_t | i_pipe_ID) |  |
| inline

Test if RX pipe is ready to receive new data.

Parameters

  i_pipe_ID | ID number of pipe. Must not be higher than UNI_MAX_PIPE

Returns
  true if ready (1). Else false (0). If i_pipe_ID is invalid, then
  return UNI_INVALID_PARAMETER (2)

UNI_RES_CODE Uniprot_Is_TX_pipe_ready | ( | uint8_t | i_pipe_ID) |  |
| inline

Test if TX pipe is ready transmit new data.

Parameters

  i_pipe_ID | ID number of pipe. Must not be higher than UNI_MAX_PIPE

Returns
  true if ready (1). Else false (0). If i_pipe_ID is invalid, then
  return UNI_INVALID_PARAMETER (2)

UNI_RES_CODE Uniprot_Is_TX_transmission_enable | ( | uint8_t | i_pipe_ID) |  |
| inline

Test if all uniprot low level data are ready to send.

This function return 1 if low level driver can begin transmit data (call function Uniprot_tx_data() ) or 0 when not ready yet.

Parameters

  i_pipe_ID | ID number of pipe. Must not be higher than UNI_MAX_PIPE

Returns
  True if flag is set (1). Else false (0). If i_pipe_ID is invalid,
  then return UNI_INVALID_PARAMETER (2)

void Uniprot_rx_data | ( | uint8_t | i_pipe_ID,
|  | uint8_t * | p_DataArray
| ) |  |

This function is called when data came from driver.

When low level driver receive data, it should call this function with
correct pipe ID number.

Parameters

  i_pipe_ID | ID number of pipe. Must not be higher than UNI_MAX_PIPE
  p_DataArray | Pointer to received data

UNI_RES_CODE Uniprot_Set_init_reinit_flag | ( | uint8_t | i_pipe_ID) |  |
| inline

Set initialize/reinitialize flag.

This flag should set only uniprot itself (only uniprot drivers). Because
it is internal function, there is not checking of pipe ID.
This function can be called externally. For example when USB is
enumerated again. In that case all data are invalid and reinitialize flag
should be set.

Parameters

  i_pipe_ID | Pipe ID (number of used pipe)

Returns
  UNI_SUCCESS if all right

void Uniprot_Task | ( | void | ) |  |
| inline

This task handle in and out data stream.

void Uniprot_tx_data | ( | uint8_t | i_pipe_ID,
|  | uint8_t * | p_DataArray
| ) |  |

This function is called when driver (and uniprot) is ready to send
data.

Parameters

  i_pipe_ID | ID number of pipe. Must not be higher than UNI_MAX_PIPE
  p_DataArray | Pointer to data to transmit