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:

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}

Version 0.5 {Malcolm Robert}

Version 1.0

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.

Module Version.

Definition at line 195 of file utils.py.

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.

 All Classes Namespaces Files Functions Variables Typedefs Properties


clearpath_base
Author(s): Mike Purvis
autogenerated on Fri Jan 11 10:11:36 2013