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

Method References

• PortHandler for Windows
• PortHandler for Linux
• PortHandler for Mac

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.