API Reference

C

C PortHandler

Description : Base functions for serial communication.
Members

Members	Description
DEFAULT_BAUDRATE	:=1000000 Default Baudrate
g_used_port_num	Shows how much ports are in-use
g_is_using	Shows whether the port is in-use

Methods

Methods	Description
portHandler	Initializes members of port data pointer struct
openPort	Opens a serial port
closePort	Closes a serial port
clearPort	Refreshes a serial port
setPortName	Sets a device name
getPortName	Gets a device name
setBaudrate	Sets a baudrate
getBaudrate	Gets a baudrate
getBytesAvailable	Checks how many bytes can be read in port buffer (Linux only)
readPort	Reads bytes from port buffer
writePort	Writes bytes to port buffer
setPacketTimeout	Sets timeout
setPacketTimeoutMSec	Sets timeout using micro second value
isPacketTimeout	Checks whether communication has been succeeded in timeout

Enumerator : None

C PortHandlerWindows

Description

PortHandler dependent functions for serial communication on Windows OS.
Members

None
Methods

Methods	Description
portHandlerWindows	Initializes parameters for serial port control
openPortWindows	Opens a serial port
closePortWindows	Closes a serial port
clearPortWindows	Refreshes a serial port
setPortNameWindows	Sets a device name
getPortNameWindows	Gets a device name
setBaudrateWindows	Sets a baudrate
getBaudrateWindows	Gets a baudrate
readPortWindows	Reads bytes from port buffer
writePortWindows	Writes bytes to port buffer
setPacketTimeoutWindows	Sets timeout
setPacketTimeoutMSecWindows	Sets timeout using micro second
isPacketTimeoutWindows	Checks whether communication has been succeeded in timeout
getCurrentTimeWindows	Gets a current time
getTimeSinceStartWindows	Gets a time since start
setupPortWindows	Sets a port

Enumerator

None

Method References

portHandlerWindows

Syntax

int portHandlerWindows(const char *port_name)

Parameters

Parameters	Description
port_name	Port name

Detailed Description

The function initializes the parameters for port control. At first, this checks if the port with same device name is set already in the portDataWindows pointer struct. If it exists, the function returns the port number as what it has. If not, the function finds any free port, resize portDataWindows struct and start to initialize struct members.

openPortWindows

Syntax
```
uint8_t openPortWindows(int port_num)
```
Parameters

Parameters	Description
port_num	Port number

Detailed Description

This function opens the port by SetBaudRateWindows function using DEFAULT_BAUDRATE. If the baudrate is needed to be changed to another baudrate value, SetBaudRateWindows function should be called again after calling openPortWindows function. When the port succeeds to be opened, this function will return true, and if not, then false.

closePortWindows

Syntax
```
void closePortWindows(int port_num)
```
Parameters

Parameters	Description
port_num	Port number

Detailed Description

This function sets serial_handle_ member of portDataWindows struct to INVALID_HANDLE_VALUE so that the #port_num port won’t be activated.

clearPortWindows

Syntax
```
void clearPortWindows(int port_num)
```
Parameters

Parameters	Description
port_num	Port number

Detailed Description

This function clears the port by purging the RX buffer.

setPortNameWindows

Syntax

void setPortNameWindows(int port_num, const char *port_name)

Parameters

Parameters	Description
port_num	Port number
port_name	Port name

Detailed Description

This function sets the device name of the #port_num port as port_name.

getPortNameWindows

Syntax
```
char *getPortNameWindows(int port_num)
```
Parameters

Parameters	Description
port_num	Port number

Detailed Description

This function returns the device name which the #port_num port is using.

setBaudrateWindows

Syntax

uint8_t setBaudrateWindows(int port_num, const int baudrate)

Parameters

Parameters	Description
port_num	Port number
baudrate	Target baudrate

Description

This function converts baudrate to baudrate type value at first. Secondly, it closes the port with ClosePort function, and opens the port with SetupPort function again. Finally, it returns port setup result.

getBaudrateWindows

Syntax

int getBaudrateWindows(int port_num)

Parameters

Parameters	Description
port_num	Port number

Description

This function returns the baudrate value previously set.

readPortWindows

Syntax

int readPortWindows(int port_num, uint8_t *packet, int length)

Parameters

Parameters	Description
port_num	Port number
packet	The number of data bytes read previously
length	Byte length for read

Description

This function gets length byte data from port buffer and returns a number of read data bytes. On end-of-file, 0 is returned, on error it returns -1.

writePortWindows

Syntax

int writePortWindows(int port_num, uint8_t *packet, int length)

Parameters

Parameters	Description
port_num	Port number
packet	The number of data bytes to write
length	Byte length for write

Description

This function transmits length byte, and returns how much the data was written. On error, it returns -1.

setPacketTimeoutWindows

Syntax

void setPacketTimeoutWindows (int port_num, uint16_t packet_length)

Parameters

Parameters	Description
port_num	Port number
packet_length	Target byte length for write

Description

This function sets the start time when it transmits the packet, and set the timeout of packet transmission to be ready for deciding communication result.

SetPacketTimeoutMSecWindows

Syntax

void SetPacketTimeoutMSecWindows (int port_num, double msec)

Parameters

Parameters	Description
port_num	Port number
msec	Miliseconds

Description

This function sets the start time with msec milisecond value when it transmits the packet, and set the timeout of packet transmission to be ready for deciding communication result.

isPacketTimeoutWindows

Syntax

uint8_t isPacketTimeoutWindows (int port_num)

Parameters

Parameters	Description
port_num	Port number

Description

This function decides the timeover of packet communication. If the time limit is over, it returns false.

getCurrentTimeWindows

Syntax

double getCurrentTimeWindows(int port_num)

Parameters

Parameters	Description
port_num	Port number

Description

This function gets a current time.

getTimeSinceStartWindows

Syntax

double getTimeSinceStartWindows(int port_num)

Parameters

Parameters	Description
port_num	Port number

Description

This function gets a time since start.

setupPortWindows

Syntax

uint8_t setupPortWindows (int port_num, const int baudrate)

Parameters

Parameters	Description
port_num	Port number
baudrate	Target baudrate

Description

This function sets the port.

C PortHandlerLinux

Description

PortHandler dependent functions for serial communication on Linux OS.
Members

None
Methods

Methods	Description
portHandleLinux	Initializes parameters for serial port control
openPortLinux	Opens a serial port
closePortLinux	Closes a serial port
clearPortLinux	Refreshes a serial port
setPortNameLinux	Sets a device name
getPortNameLinux	Gets a device name
setBaudrateLinux	Sets a baudrate
getBaudrateLinux	Gets a baudrate
getBytesAvailableLinux	Checks how many bytes can be read in port buffer
readPortLinux	Reads bytes from port buffer
writePortLinux	Writes bytes to port buffer
setPacketTimeoutLinux	Sets timeout
setPacketTimeoutMSecLinux	Sets timeout using micro second
isPacketTimeoutLinux	Checks whether communication has been succeeded in timeout
getCurrentTimeLinux	Gets a current time
getTimeSinceStartLinux	Gets a time since start
setupPortLinux	Sets a port
setCustomBaudrateLinux	Sets a custom baudrate
getCFlagBaud	Gets a baudrate

Enumerator

None

Method References

portHandlerLinux

Syntax

int portHandlerLinux(const char *port_name)

Parameters

Parameters	Description
port_name	Port name

Detailed Description

The function initializes the parameters for port control. At first, this checks if the port with same device name is set already in the portDataLinux pointer struct. If it exists, the function returns the port number as what it has. If not, the function finds any free port, resize portDataLinux struct and start to initialize struct members.

openPortLinux

Syntax
```
uint8_t openPortLinux(int port_num)
```
Parameters

Parameters	Description
port_num	Port number

Detailed Description

This function opens the port by SetBaudRateLinux function using DEFAULT_BAUDRATE. If the baudrate is needed to be changed to another baudrate value, SetBaudRateLinux function should be called again after calling OpenPortLinux function. When the port succeeds to be opened, this function will return true, and if not, then false.

closePortLinux

Syntax
```
void closePortLinux(int port_num)
```
Parameters

Parameters	Description
port_num	Port number

Detailed Description

This function closes the port by closing the file descriptor.

clearPortLinux

Syntax
```
void clearPortLinux(int port_num)
```
Parameters

Parameters	Description
port_num	Port number

Detailed Description

This function clears the port by flushing the file descriptor.

setPortNameLinux

Syntax

void setPortNameLinux(int port_num, const char *port_name)

Parameters

Parameters	Description
port_num	Port number
port_name	Port name

Detailed Description

This function sets the device name as port_name.

getPortNameLinux

Syntax
```
char *getPortNameLinux(int port_num)
```
Parameters

Parameters	Description
port_num	Port number

Detailed Description

This function returns the device name which the port is using.

setBaudrateLinux

Syntax

uint8_t setBaudrateLinux(int port_num, const int baudrate)

Parameters

Parameters	Description
port_num	Port number
baudrate	Target baudrate

Description

This function converts baudrate to baudrate type value at first. Secondly, it closes the port with ClosePortLinux function, and opens the port with SetupPortLinux function again. If the value of baudrate is not in the compatible baudrate list, the SetCustomBaudrateLinux function suggests the baudrate value which is closest of available baudrate value. Finally, it returns false.

getBaudrateLinux

Syntax

int getBaudrateLinux(int port_num)

Parameters

Parameters	Description
port_num	Port number

Description

This function returns the baudrate value previously set.

getBytesAvailableLinux

Syntax

int getBytesAvailableLinux(int port_num)

Parameters

Parameters	Description
port_num	Port number

Description

This function checks how much the data can be read, and returns its length.

readPortLinux

Syntax

int readPortLinux(int port_num, uint8_t *packet, int length)

Parameters

Parameters	Description
port_num	Port number
packet	The number of data bytes read previously
length	Byte length for read

Description

This function gets length byte data from port buffer and returns a number of read data bytes. On end-of-file, 0 is returned, on error it returns -1.

writePortLinux

Syntax

int writePortLinux(int port_num, uint8_t *packet, int length)

Parameters

Parameters	Description
port_num	Port number
packet	The number of data bytes to write
length	Byte length for write

Description

This function transmits length byte, and returns how much the data was written. On error, it returns -1.

setPacketTimeoutLinux

Syntax

void setPacketTimeoutLinux (int port_num, uint16_t packet_length)

Parameters

Parameters	Description
port_num	Port number
Packet_length	Target byte length for write

Description

This function sets the start time when it transmits the packet, and set the timeout of packet transmission to be ready for deciding communication result.

setPacketTimeoutMSecLinux

Syntax

void setPacketTimeoutMSecLinux (int port_num, double msec)

Parameters

Parameters	Description
port_num	Port number
msec	Miliseconds

Description

This function sets the start time with msec milisecond value when it transmits the packet, and set the timeout of packet transmission to be ready for deciding communication result.

isPacketTimeoutLinux

Syntax

uint8_t isPacketTimeoutLinux(int port_num)

Parameters

Parameters	Description
port_num	Port number

Description

This function decides the timeover of packet communication. If the time limit is over, it returns false.

getCurrentTimeLinux

Syntax

double getCurrentTimeLinux()

Parameters

None
Description

This function gets a current time.

getTimeSinceStartLinux

Syntax

double getTimeSinceStartLinux(int port_num)

Parameters

Parameters	Description
port_num	Port number

Description

This function gets a time since start.

setupPortLinux

Syntax

uint8_t setupPortLinux(int port_num, int cflag_baud)

Parameters

Parameters	Description
port_num	Port number
cflag_baud	Target baudrate

Description

This function sets the port.

setCustomBaudrateLinux

Syntax

uint8_t setCustomBaudrateLinux(int port_num, int speed)

Parameters

Parameters	Description
port_num	Port number
speed	communication speed

Description

This function sets a custom baudrate.

getCFlagBaud

Syntax

int getCFlagBaud(int baudrate)

Parameters

Parameters	Description
baudrate	Target baudrate

Description

This function gets the baudrate.

C PortHandlerMac

Description

PortHandler dependent functions for serial communication on Mac OS.
Members

None
Methods

Methods	Description
portHandleMac	Initializes parameters for serial port control
openPortMac	Opens a serial port
closePortMac	Closes a serial port
clearPortMac	Refreshes a serial port
setPortNameMac	Sets a device name
getPortNameMac	Gets a device name
setBaudrateMac	Sets a baudrate
getBaudrateMac	Gets a baudrate
getBytesAvailableMac	Checks how many bytes can be read in port buffer
readPortMac	Reads bytes from port buffer
writePortMac	Writes bytes to port buffer
setPacketTimeoutMac	Sets timeout
setPacketTimeoutMSecMac	Sets timeout using micro
isPacketTimeoutMac	Checks whether communication has been succeeded in timeout
getCurrentTimeMac	Gets a current time
getTimeSinceStartMac	Gets a time since start
setupPortMac	Sets a port
setCustomBaudrateMac	Sets a custom baudrate
getCFlagBaud	Gets a baudrate

Enumerator

None

Method References

portHandlerMac

Syntax

int portHandlerMac(const char *port_name)

Parameters

Parameters	Description
port_name	Port name

Detailed Description

The function initializes the parameters for port control. At first, this checks if the port with same device name is set already in the portDataMac pointer struct. If it exists, the function returns the port number as what it has. If not, the function finds any free port, resize portDataMac struct and start to initialize struct members.

openPortMac

Syntax
```
uint8_t openPortMac(int port_num)
```
Parameters

Parameters	Description
port_num	Port number

Detailed Description

This function opens the port by SetBaudRateMac function using DEFAULT_BAUDRATE. If the baudrate is needed to be changed to another baudrate value, SetBaudRateMac function should be called again after calling OpenPortMac function. When the port succeeds to be opened, this function will return true, and if not, then false.

closePortMac

Syntax
```
void closePortMac(int port_num)
```
Parameters

Parameters	Description
port_num	Port number

Detailed Description

This function closes the port by closing the file descriptor.

clearPortMac

Syntax
```
void clearPortMac(int port_num)
```
Parameters

Parameters	Description
port_num	Port number

Detailed Description

This function clears the port by flushing the file descriptor.

setPortNameMac

Syntax

void setPortNameMac(int port_num, const char *port_name)

Parameters

Parameters	Description
port_num	Port number
port_name	Port name

Detailed Description

This function sets the device name as port_name.

getPortNameMac

Syntax
```
char *getPortNameMac(int port_num)
```
Parameters

Parameters	Description
port_num	Port number

Detailed Description

This function returns the device name which the port is using.

setBaudrateMac

Syntax

uint8_t setBaudrateMac(int port_num, const int baudrate)

Parameters

Parameters	Description
port_num	Port number
baudrate	Target baudrate

Description

This function converts baudrate to baudrate type value at first. Secondly, it closes the port with ClosePortMac function, and opens the port with SetupPortMac function again. If the value of baudrate is not in the compatible baudrate list, the SetCustomBaudrateMac function suggests the baudrate value which is closest of available baudrate value. Finally, it returns false.

getBaudrateMac

Syntax

int getBaudrateMac(int port_num)

Parameters

Parameters	Description
port_num	Port number

Description

This function returns the baudrate value previously set.

getBytesAvailableMac

Syntax

int getBytesAvailableMac(int port_num)

Parameters

Parameters	Description
port_num	Port number

Description

This function checks how much the data can be read, and returns its length.

readPortMac

Syntax

int readPortMac(int port_num, uint8_t *packet, int length)

Parameters

Parameters	Description
port_num	Port number
packet	The number of data bytes read previously
length	Byte length for read

Description

This function gets length byte data from port buffer and returns a number of read data bytes. On end-of-file, 0 is returned, on error it returns -1.

writePortMac

Syntax

int writePortMac(int port_num, uint8_t *packet, int length)

Parameters

Parameters	Description
port_num	Port number
packet	The number of data bytes to write
length	Byte length for write

Description

This function transmits length byte, and returns how much the data was written. On error, it returns -1.

setPacketTimeoutMac

Syntax

void setPacketTimeoutMac (int port_num, uint16_t packet_length)

Parameters

Parameters	Description
port_num	Port number
Packet_length	Target byte length for write

Description

This function sets the start time when it transmits the packet, and set the timeout of packet transmission to be ready for deciding communication result.

setPacketTimeoutMSecMac

Syntax

void setPacketTimeoutMSecMac (int port_num, double msec)

Parameters

Parameters	Description
port_num	Port number
msec	Miliseconds

Description

This function sets the start time with msec milisecond value when it transmits the packet, and set the timeout of packet transmission to be ready for deciding communication result.

isPacketTimeoutMac

Syntax

uint8_t isPacketTimeoutMac(int port_num)

Parameters

Parameters	Description
port_num	Port number

Description

This function decides the timeover of packet communication. If the time limit is over, it returns false.

getCurrentTimeMac

Syntax

double getCurrentTimeMac()

Parameters

None
Description

This function gets a current time.

getTimeSinceStartMac

Syntax

double getTimeSinceStartMac(int port_num)

Parameters

Parameters	Description
port_num	Port number

Description

This function gets a time since start.

setupPortMac

Syntax

uint8_t setupPortMac(int port_num, int cflag_baud)

Parameters

Parameters	Description
port_num	Port number
cflag_baud	Target baudrate

Description

This function sets the port.

setCustomBaudrateMac

Syntax

uint8_t setCustomBaudrateMac(int port_num, int speed)

Parameters

Parameters	Description
port_num	Port number
speed	communication speed

Description

This function sets a custom baudrate.

getCFlagBaud

Syntax

int getCFlagBaud(int baudrate)

Parameters

Parameters	Description
baudrate	Target baudrate

Description

This function gets the baudrate.