Module.
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}
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