# Serial
[Core]

Send and receive data via the Make Controller's serial ports. More...

## Defines
#define | SERIAL_0 0
| Index to be used to specify serial port 0.
#define | SERIAL_1 1
| Index to be used to specify serial port 1.
## Functions
int | Serial_SetActive (int index, int state)
| Set the active state of a serial port.
bool | Serial_GetActive (int index)
| Read the active state of the Serial subsystem.
int | Serial_Write (int index, uchar *buffer, int count, int timeout)
| Write a block of data to the Serial port.
int | Serial_Read (int index, uchar *buffer, int size, int timeout)
| Read data from the Serial port.
int | Serial_GetReadable (int index)
| Returns the number of bytes in the queue waiting to be read.
int | Serial_SetChar (int index, int character)
| Sends a character (in the range of 0 to 255) to the write queue.
int | Serial_SetBaud (int index, int baud)
| Sets the serial baud rate.
int | Serial_SetBits (int index, int bits)
| Sets the number of bits per character.
int | Serial_SetParity (int index, int parity)
| Sets the parity.
int | Serial_SetStopBits (int index, int stopBits)
| Sets the stop bits per character.
int | Serial_SetHardwareHandshake (int index, int hardwareHandshake)
| Sets whether hardware handshaking is being used.
int | Serial_GetChar (int index)
| Returns a single character from the receive queue if available.
int | Serial_GetBaud (int index)
| Returns the current baud rate.
int | Serial_GetBits (int index)
| Returns the number of bits for each character.
int | Serial_GetParity (int index)
| Returns the current parity.
int | Serial_GetStopBits (int index)
| Returns the number of stop bits.
int | Serial_GetHardwareHandshake (int index)
| Returns whether hardware handshaking is being employed or not.
void | Serial_Flush (int index)
| Clear out the serial port.
void | Serial_ClearErrors (int index)
| Reset the error flags in the serial system.
bool | Serial_GetErrors (int index, bool *overrun, bool *frame, bool *parity)
| Read whether there are any errors.
void | Serial_StartBreak (int index)
| Start the transimission of a break.
void | Serial_StopBreak (int index)
| Stop the transimission of a break.

## Detailed Description

Send and receive data via the Make Controller's serial ports.

There are 2 full serial ports on the Make Controller, and this library provides support for both of them.

Control all of the common serial characteristics including:

- baud - the speed of the connection (110 - > 2M) in baud or raw bits per second. 9600 baud is the default setting.
- bits - the size of each character (5 - 8). 8 bits is the default setting.
- stopBits - the number of stop bits transmitted (1 or 2) 1 stop bit is the default setting.
- parity - the parity policy (-1 is odd, 0 is none and 1 is even). Even is the default setting.
- hardwareHandshake - whether hardware handshaking is used or not. HardwareHandshaking is off by default.

The subsystem is supplied with small input and output buffers (of 100 characters each) and at present the implementation is interrupt per character so it's not particularly fast.

Todo:
  Convert to DMA interface for higher performance, and add support for debug UART

## Function Documentation

void Serial_ClearErrors | ( | int | index | ) |

Reset the error flags in the serial system.

In the normal course of operation, the serial system may experience a variety of different error modes, including buffer overruns, framing and parity errors, and more. When in an error state, the serial system may behave differently than normal.

Serial_ClearErrors() resets the appropriate status bits to a state of normal operation. It will only reset the error states if there are currently any errors.

Parameters:

  | index | Which serial port - SERIAL_0 or SERIAL_1

See also:
  Serial_GetErrors

Example

      Serial_ClearErrors(SERIAL_0);
      // that's all there is to it.

Definition at line 529 of file serial.c.

void Serial_Flush | ( | int | index | ) |

Clear out the serial port.

Ensures that there are no bytes in the incoming buffer.

Parameters:

  | index | Which serial port - SERIAL_0 or SERIAL_1

Example

      Serial_SetActive(SERIAL_0, 1);
      Serial_Flush(SERIAL_0); // after starting up, make sure there's no junk in there

Definition at line 499 of file serial.c.

bool Serial_GetActive | ( | int | index | ) |

Read the active state of the Serial subsystem.

Parameters:

  | index | Which serial port - SERIAL_0 or SERIAL_1

Returns:
  State - 1/non-zero (on) or 0 (off).

Definition at line 100 of file serial.c.

int Serial_GetBaud | ( | int | index | ) |

Returns the current baud rate.

Parameters:

  | index | Which serial port - SERIAL_0 or SERIAL_1

Returns:
  baud

Definition at line 398 of file serial.c.

int Serial_GetBits | ( | int | index | ) |

Returns the number of bits for each character.

Parameters:

  | index | Which serial port - SERIAL_0 or SERIAL_1

Returns:
  bits

Definition at line 417 of file serial.c.

int Serial_GetChar | ( | int | index | ) |

Returns a single character from the receive queue if available.

This character is returned unsigned - i.e. having a value of 0 - 255. The return value is -1 if there is no character waiting.

Parameters:

  | index | Which serial port - SERIAL_0 or SERIAL_1

Returns:
  character from the queue or -1 if there is no character.

Definition at line 367 of file serial.c.

bool Serial_GetErrors | ( | int | index,
|  | bool * | overrun,
|  | bool * | frame,
|  | bool * | parity |
| ) |  |  |

Read whether there are any errors.

We can check for three kinds of errors in the serial system:

- buffer overrun
- framing error
- parity error

Each parameter will be set with a true or a false given the current error state. If you don't care to check one of the parameters, just pass in 0.

Parameters:

  | index | Which serial port - SERIAL_0 or SERIAL_1
  | overrun | A bool that will be set with the overrun error state.
  | frame | A bool that will be set with the frame error state.
  | parity | A bool that will be set with the parity error state.

Returns:
  True if there were any errors, false if there were no errors.

See also:
  Serial_ClearErrors( )

Example

      bool over, fr, par;
      if( Serial_GetErrors( SERIAL_0, &over, &fr, &par ) )
      {
        // if we wanted, we could just clear them all right here with Serial_ClearErrors()
        // but here we'll check to see what kind of errors we got
        if(over)
        {
          // then we have an overrun error
        }
        if(fr)
        {
          // then we have a framing error
        }
        if(par)
        {
          // then we have a parity error
        }
      }
      else
      {
        // there were no errors
      }

Definition at line 583 of file serial.c.

int Serial_GetHardwareHandshake | ( | int | index | ) |

Returns whether hardware handshaking is being employed or not.

Parameters:

  | index | Which serial port - SERIAL_0 or SERIAL_1

Returns:
  hardwareHandshake

Definition at line 474 of file serial.c.

int Serial_GetParity | ( | int | index | ) |

Returns the current parity.

-1 means odd, 0 means none, 1 means even

Parameters:

  | index | Which serial port - SERIAL_0 or SERIAL_1

Returns:
  parity

Definition at line 436 of file serial.c.

int Serial_GetReadable | ( | int | index | ) |

Returns the number of bytes in the queue waiting to be read.

Parameters:

  | index | Which serial port - SERIAL_0 or SERIAL_1

Returns:
  bytes in the receive queue.

Definition at line 193 of file serial.c.

int Serial_GetStopBits | ( | int | index | ) |

Returns the number of stop bits.

Parameters:

  | index | Which serial port - SERIAL_0 or SERIAL_1

Returns:
  stopBits

Definition at line 455 of file serial.c.

int Serial_Read | ( | int | index,
|  | uchar * | buffer,
|  | int | size,
|  | int | timeout |
| ) |  |  |

Read data from the Serial port.

Will block for the time specified (in ms) if there are insufficient characters. Blocking can be avoided if Serial_GetReadable( ) is used to determine how many characters are available to read prior to calling this function.

Parameters:

  | index | Which serial port - SERIAL_0 or SERIAL_1
  | buffer | A pointer to the buffer to read into.
  | size | An integer specifying the maximum number of bytes to read.
  | timeout | Time in milliseconds to block waiting for the specified number of bytes. 0 means don't wait.

Returns:
  number of bytes read (>=0) or error <0 .

Definition at line 161 of file serial.c.

int Serial_SetActive | ( | int | index,
|  | int | state |
| ) |  |  |

Set the active state of a serial port.

This is automatically set to true by any call to Serial_Write or Serial_Read.

Parameters:

  | index | Which serial port - SERIAL_0 or SERIAL_1
  | state | An integer specifying the active state - 1 (on) or 0 (off).

Returns:
  CONTROLLER_OK (=0) on success.

Definition at line 80 of file serial.c.

int Serial_SetBaud | ( | int | index,
|  | int | baud |
| ) |  |  |

Sets the serial baud rate.

Parameters:

  | index | Which serial port - SERIAL_0 or SERIAL_1
  | baud | The desired baud rate.

Returns:
  status.

Definition at line 240 of file serial.c.

int Serial_SetBits | ( | int | index,
|  | int | bits |
| ) |  |  |

Sets the number of bits per character.

5 - 8 are legal values. 8 is the default.

Parameters:

  | index | Which serial port - SERIAL_0 or SERIAL_1
  | bits | bits per character

Returns:
  status.

Definition at line 263 of file serial.c.

int Serial_SetChar | ( | int | index,
|  | int | character |
| ) |  |  |

Sends a character (in the range of 0 to 255) to the write queue.

Parameters:

  | index | Which serial port - SERIAL_0 or SERIAL_1
  | character | The character to be sent. Must be 0 <= c < 256.

Returns:
  status.

Definition at line 209 of file serial.c.

int Serial_SetHardwareHandshake | ( | int | index,
|  | int | hardwareHandshake |
| ) |  |  |

Sets whether hardware handshaking is being used.

Parameters:

  | index | Which serial port - SERIAL_0 or SERIAL_1
  | hardwareHandshake | sets hardware handshaking on (1) or off (0)

Returns:
  status.

Definition at line 343 of file serial.c.

int Serial_SetParity | ( | int | index,
|  | int | parity |
| ) |  |  |

Sets the parity.

-1 is odd, 0 is none, 1 is even. The default is none - 0.

Parameters:

  | index | Which serial port - SERIAL_0 or SERIAL_1
  | parity | -1, 0 or 1.

Returns:
  status.

Definition at line 290 of file serial.c.

int Serial_SetStopBits | ( | int | index,
|  | int | stopBits |
| ) |  |  |

Sets the stop bits per character.

1 or 2 are legal values. 1 is the default.

Parameters:

  | index | Which serial port - SERIAL_0 or SERIAL_1
  | stopBits | stop bits per character

Returns:
  status.

Definition at line 316 of file serial.c.

void Serial_StartBreak | ( | int | index | ) |

Start the transimission of a break.

This has no effect if a break is already in progress.

Parameters:

  | index | Which serial port - SERIAL_0 or SERIAL_1

Example

      Serial_StartBreak(SERIAL_0);

Definition at line 623 of file serial.c.

void Serial_StopBreak | ( | int | index | ) |

Stop the transimission of a break.

This has no effect if there's not a break already in progress.

Parameters:

  | index | Which serial port - SERIAL_0 or SERIAL_1

Example

      Serial_StopBreak(SERIAL_0);

Definition at line 641 of file serial.c.

int Serial_Write | ( | int | index,
|  | uchar * | buffer,
|  | int | count,
|  | int | timeout |
| ) |  |  |

Write a block of data to the Serial port.

Will block for the time specified (in ms) if the queue fills up.

Parameters:

  | index | Which serial port - SERIAL_0 or SERIAL_1
  | buffer | A pointer to the buffer to write from.
  | count | An integer specifying the number of bytes to write.
  | timeout | Time in milliseconds to block waiting for the queue to free up. 0 means don't wait.

Returns:
  status.

Definition at line 119 of file serial.c.