clearpath::utils Namespace Reference

Clearpath Robotics Inc. More...

Classes
class	ChecksumError
	Checksum Exception. More...
class	FormatError
	Format Exception. More...
class	NullLoggingHandler
	Null Logging Handler. More...
class	SubscriptionError
	Subscription Exception. More...
class	TimeoutError
	Timeout Exception. More...
class	TransportError
	Transport Exception. More...
class	UnsupportedCodeError
	Unsupported Code Exception. More...
Functions
def	ccitt_checksum
	Perform a 16-bit CRC with CCITT Polynomial 0x1021.
def	from_ascii
	From ASCII to Byte List.
def	from_byte
	From Byte to Byte List.
def	from_char
	From Char to Byte List.
def	from_int
	From Int to Byte List.
def	from_short
	From Short to Byte List.
def	from_unsigned_int
	From Unsigned Int to Byte List.
def	from_unsigned_short
	From Unsigned Short to Byte List.
def	hex
	Byte to Hex String.
def	list_serial_ports
	List machine serial ports.
def	to_ascii
	From Byte List to ASCII.
def	to_byte
	From Byte List to Byte.
def	to_bytes
	From Byte List to bytes.
def	to_char
	From Byte List to Char.
def	to_int
	From Byte List to Int.
def	to_short
	From Byte List to Short.
def	to_unsigned_int
	From Byte List to Unsigned Int.
def	to_unsigned_short
	From Byte List to Unsigned Short.
Variables
string	__revision__ = "$Revision: 674 $"
	SVN Code Revision.
string	__version__ = "1.0"
	Module Version.
tuple	CCIT_CRC_TABLE
	Precomputed checksum table.
tuple	logger = logging.getLogger('clearpath.utils')
	Message Log.

Detailed Description

Clearpath Robotics Inc.

Utilities Python Module

Utilities for use with Horizon and other Clearpath Modules

Contains:

Byte List Conversions
Checksum Utilities: 16-bit CRC - CCITT polynomial x16+x12+x5+1 (0x1021)
Common Exceptions
Logging Utilities
Transport Utilities

Author:: Ryan Gariepy; Malcolm Robert

Date:: 18/01/10 pySerial [http://pyserial.sourceforge.net/]
-- for list_serial_ports()

Version:: 1.0

USE

The intended purpose of this module is to contain common classes and methods that are (or could be) used in multiple Clearpath Python packages and/or modules and do not provide functionality specific to one package (hence utilities).

Due to backward support for Python 2.6 and the lack of support for bytes in Python 2.6, it is useful to store an array of bytes as an array of numbers. Without strict types, this presents requirements for extracting and appending numbers of various types to the byte list. The methods that begin with 'from_' take the number of the appropriate type (or ascii string for from_ascii) and converts it to an array of numbers all within [0,255] that can be appended or inserted into other arrays. Likewise, the methods that begin with 'to_' takes an array of numbers (must be of proper size) and converts it to the desired type. Since most streams in 2.6 use strings and streams in 3.x use bytes, the method to_bytes can be used to convert the array of numbers into the appropriate format. Further, the method hex is provided to display a number [0,255] in hex form (in a format preferable to python's default hex method).

The method ccitt_checksum provides a 16-bit CRC table based checksum on the given array of numbers (each [0,255]) using the CCITT Polynomial (0x1021). Checksums are very useful for verifying data is transmitted without error.

The Python standard built-ins do not provide many exception classes. To help differentiate the types of errors encountered, the exceptions ChecksumError, FormatError, SubscriptionError, TransportError, TimeoutError, and UnsupportedCodeError are provided without any additional functionality added beyond their parent classes.

The majority of Clearpath's Python code is in library form, intended to be used by other scripts/programs/libraries. While logging debug messages is useful, developers do not expect libraries to be logging messages by default so the class NullLoggingHandler is provided to disable the default logging action. For library loggers, set the logging level to NOTSET, set propagate to False and add an instance of NullLoggingHandler as the only logging handler and all messages will be rendered disabled.

While actual communication over RS-232 (serial) is typically package specific and not common, programs/scripts that invoke communication packages find it useful to be able to find out what serial ports exist and are accessible on the computer. For that purpose, the method list_serial_ports is provided. Note that this method requires the non-standard Python library pySerial to be installed into the Python search path.

Various logging messages (debug, warning,...) are logged with the standard Python logger to the log named 'clearpath.utils'.
Messages are ignored by default; remove the only handler from it and turn on propagation to get messages to propagate.

HISTORY

Version 0.1 - 0.3 {Ryan Gariepy}

Initial Creation in protocol.py

Version 0.5 {Malcolm Robert}

Move to clearpath_utils.py
Added Serial Port Listing
Added TransportError
Added Logging Utils
Added Doxygen documentation
Added independent version scheme

Version 1.0

Added Exceptions
Python 2.6+ & 3.x compatible

License

Function Documentation

def clearpath::utils::ccitt_checksum	(	data,
		init_val = `0xFFFF`
	)

Perform a 16-bit CRC with CCITT Polynomial 0x1021.

Parameters:

	data	A Byte List to checksum
	init_val	The initial value to calculate the checksum with. The default value of 0xffff performs a proper checksum.

Returns:: Resultant Checksum (16-bits)

Perform a 16-bit CRC with CCITT Polynomial 0x1021

Definition at line 764 of file utils.py.

def clearpath::utils::from_ascii ( input )

From ASCII to Byte List.

Convert a string of ASCII to a byte list.

Parameters:

input

The string to convert to a byte list

Returns:: byte list

ASCII -> Byte List

Definition at line 569 of file utils.py.

def clearpath::utils::from_byte	(	input,
		scale = `1`
	)

From Byte to Byte List.

Convert an unsigned byte to a byte list.

Parameters:

input

The number to convert to a byte list [0,255]

Returns:: byte list

Byte -> Byte List

Definition at line 434 of file utils.py.

def clearpath::utils::from_char	(	input,
		scale = `1`
	)

From Char to Byte List.

Convert a signed byte to a byte list. Do not pass an actual character to this function; if you need to convert an actual character use from_byte(ord(character)).

Parameters:

input

The number to convert to a byte list [-128,127]

Returns:: byte list

Char -> Byte List

Definition at line 248 of file utils.py.

def clearpath::utils::from_int	(	input,
		scale = `1`
	)

From Int to Byte List.

Convert a signed integer to a byte list.

Parameters:

input

The number to convert to a byte list [-2147483648, 2147483647]

Returns:: byte list

Int -> Byte List

Definition at line 365 of file utils.py.

def clearpath::utils::from_short	(	input,
		scale = `1`
	)

From Short to Byte List.

Convert a signed short to a byte list.

Parameters:

input

The number to convert to a byte list [-32768, 32767]

Returns:: byte list

Short -> Byte List

Definition at line 305 of file utils.py.

def clearpath::utils::from_unsigned_int	(	input,
		scale = `1`
	)

From Unsigned Int to Byte List.

Convert an unsigned integer to a byte list.

Parameters:

input

The number to convert to a byte list [0, 4294967295]

Returns:: byte list

Unsigned Int -> Byte List

Definition at line 520 of file utils.py.

def clearpath::utils::from_unsigned_short	(	input,
		scale = `1`
	)

From Unsigned Short to Byte List.

Convert an unsigned short to a byte list.

Parameters:

input

The number to convert to a byte list [0, 65535]

Returns:: byte list

Unsigned Short -> Byte List

Definition at line 475 of file utils.py.

def clearpath::utils::hex ( byte )

Byte to Hex String.

Display a byte in a string as HEX.

Parameters:

byte

The byte to display

Returns:: string

Byte to Hex String

Definition at line 226 of file utils.py.

def clearpath::utils::list_serial_ports ( )

List machine serial ports.

Utility to get a listing of OS known serial ports.

Posix: Lists devices in /dev that matches ttyS# or ttyUSB#
Degrades to listing devices accessible by the serial module
Windows: Lists COM devices accessible by the serial module

pySerial [http://pyserial.sourceforge.net/]

Precondition:: OS must be Posix compliant or Windows NT; Posix: Read access on /dev or full access of Serial ports; Windows: Full access of COM ports

Exceptions:

	OSError	If Unsupported OS (not Posix or Windows)
	IOError	If can't read '/dev' on Posix

Returns:: List of serial port names ('/dev/ttyS0', '/dev/ttyUSB0', 'COM0'), Empty List if none found

List machine serial ports.

Definition at line 880 of file utils.py.

def clearpath::utils::to_ascii ( input )

From Byte List to ASCII.

Convert a byte list to an ASCII string.

Parameters:

input

The byte list to convert to an ASCII string

Returns:: ASCII string

Byte List -> ASCII

Definition at line 592 of file utils.py.

def clearpath::utils::to_byte ( input )

From Byte List to Byte.

Convert a byte list to an unsigned byte.

Parameters:

input

The byte list to convert to an unsigned byte [byte]

Returns:: unsigned byte

Byte List -> Byte

Definition at line 457 of file utils.py.

def clearpath::utils::to_bytes ( input )

From Byte List to bytes.

Convert a byte list to a bytes type.

Parameters:

input

The byte list to convert to bytes

Returns:: bytes string

Byte List -> bytes

Definition at line 607 of file utils.py.

def clearpath::utils::to_char	(	input,
		scale = `1`
	)

From Byte List to Char.

Convert a byte list to a signed byte.

Parameters:

input

The byte list to convert to a signed byte [byte]

Returns:: signed byte

Byte List -> Char

Definition at line 278 of file utils.py.

def clearpath::utils::to_int	(	input,
		scale = `1`
	)

From Byte List to Int.

Convert a byte list to a signed integer.

Parameters:

input

The byte list to convert to a signed integer [byte,byte,byte,byte]

Returns:: signed integer

Byte List -> Int

Definition at line 400 of file utils.py.

def clearpath::utils::to_short	(	input,
		scale = `1`
	)

From Byte List to Short.

Convert a byte list to a signed short.

Parameters:

input

The byte list to convert to a signed short [byte,byte]

Returns:: signed short

Byte List -> Short

Definition at line 337 of file utils.py.

def clearpath::utils::to_unsigned_int ( input )

From Byte List to Unsigned Int.

Convert a byte list to an unsigned integer.

Parameters:

input

The byte list to convert to an unsigned integer [byte,byte,byte,byte]

Returns:: unsigned integer

Byte List -> Unsigned Int

Definition at line 545 of file utils.py.

def clearpath::utils::to_unsigned_short ( input )

From Byte List to Unsigned Short.

Convert a byte list to an unsigned short.

Parameters:

input

The byte list to convert to an unsigned short [byte,byte]

Returns:: unsigned short

Byte List -> Unsigned Short

Definition at line 498 of file utils.py.

Variable Documentation

string clearpath::utils::__revision__ = "$Revision: 674 $"

SVN Code Revision.

Definition at line 198 of file utils.py.

string clearpath::utils::__version__ = "1.0"

Module Version.

Definition at line 195 of file utils.py.

tuple clearpath::utils::CCIT_CRC_TABLE

Precomputed checksum table.

Polynomial 0x1021.

Used for performing a 16-bit CRC with polynomial 0x1021

Definition at line 719 of file utils.py.

tuple clearpath::utils::logger = logging.getLogger('clearpath.utils')

Message Log.

Definition at line 203 of file utils.py.

clearpath::utils Namespace Reference

Classes

Functions

Variables

Detailed Description

USE

HISTORY

License

Function Documentation

Variable Documentation