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:

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.