hachi documentation - media.readthedocs.org filehachi documentation, release 0.5.1 class...

hachi DocumentationRelease 0.5.1

Antoine Bertin

April 10, 2014

Contents

i

hachi Documentation, Release 0.5.1

Release v0.5.1

Hachi is a Python library to interact with XBees.

Contents 1


2 Contents

CHAPTER 1

Serial implementation

Read XBeeResponse:

>>> import hachi>>> from hachi.serial import XBeeSerial>>> x = XBeeSerial(’/dev/ttyUSB0’)>>> x.read_response()<ZBIoSampleResponse(len=18)>

Send XBeeRequest:

>>> request = hachi.AtRequest(’ID’, 0xff)>>> x.send(request)>>> response = x.read_response()>>> response<AtResponse(len=xx)>>>> response.status == hachi.COMMAND_STATUS_OKTrue

3


4 Chapter 1. Serial implementation

CHAPTER 2

Twisted implementation

Use the XBeeProtocol:

>>> import hachi>>> from hachi.twisted import XBeeProtocol>>> from twisted.internet import reactor>>> from twisted.internet.serialport import SerialPort>>> class TestXBee(XBeeProtocol):... def responseReceived(self, response):... print(response)...>>> serial = SerialPort(TestXBee(), ’/dev/ttyUSB0’, reactor, baudrate=9600)>>> reactor.run()<ZBIoSampleResponse(len=18)><ZBIoSampleResponse(len=18)><ZBIoSampleResponse(len=18)>

5


6 Chapter 2. Twisted implementation

CHAPTER 3

API Documentation

If you are looking for information on a specific function, class or method, this part of the documentation is for you.

3.1 Core

class hachi.core.XBee(callback=None)Parser for incoming XBee communications

The XBee parses data through its feed() method. When a complete and valid response is found, the responseattribute is set to the corresponding XBeeResponse and the callback is called. Any malformed response issilently discarded.

Parameters callback (function) – callback method called with a XBeeResponse as first positionalargument

reset()Reset the state of the parser

feed(data)Feed the parser with data

Parameters data (int or bytes or bytearray) – byte(s) to add

hachi.core.escape(byte)Escape a byte

Parameters byte (int) – the byte to escape

Raise ValueError if the byte is not a special byte

Returns the escaped byte

Return type int

hachi.core.escape_frame(frame)Escape a frame

Parameters frame (bytearray) – the frame to escape, starting with FRAME_DELIMITER

Raise ValueError if the frame does not start with a FRAME_DELIMITER

Returns the escaped frame

Return type bytearray

hachi.core.unescape(byte)Unescape a byte

7


Parameters byte (int) – the byte to unescape

Raise ValueError if the unescaped byte is not a special byte

Returns the unescaped byte

Return type int

3.2 Response

3.2.1 Responses

class hachi.response.XBeeResponse(frame)Base class for all XBee responses

The XBeeResponse is a wrapper around the underlying raw API frame.

Parameters frame (bytearray) – unescaped raw API frame

api_id = NoneAPI ID

Subclasses must implement this and return the corresponding API ID

frame = NoneUnescaped raw API frame

lengthLength, on 2 bytes starting right after the FRAME_DELIMITER of the frame

id_dataAPI ID-specific raw data, bytes between the api_id and the checksum

Subclasses may provide properties to access API ID-specific data

checksumChecksum, last byte of the frame

verify()Check if the response has a valid checksum

Returns True if the response has a valid checksum, False otherwise

Return type bool

class hachi.response.Rx64Response(frame)Response to a Tx64Request

Frame example: 7E 00 10 80 00 13 A2 00 40 52 2B AA 16 03 F1 2E AA BD C9 FB

source_addressSource address, first 8 bytes of the id_data

rssiRSSI, immediatly following the source_address

optionsOptions, immediatly following the rssi

dataData, all bytes following the options until the end of the id_data

8 Chapter 3. API Documentation


class hachi.response.Rx16Response(frame)Response to a Tx16Request

Frame example: 7E 00 0A 81 52 1A 23 01 12 33 85 A1 F2 91’





class hachi.response.Rx64IoSampleResponse(frame)IO sample response using 64-bits addressing

Frame example: 7E 00 14 82 00 13 A2 00 40 52 2B AA 23 01 02 14 88 00 80 00 8F 03 ED 00 08 02 4C 00 0C3E




sample_countSample count, immediatly following the options

analog_maskAnalog mask, immediatly following the sample_count

It is the whole byte of which first and last bit are set to 0 because useless in this context. Second bit (rightto left) tells if analog channel 0 (A0) is enabled (bit to 1) or disabled (bit to 0), third bit is for A1 and soon until seventh bit which is for A5

digital_maskDigital mask, on 2 bytes including the analog_mask byte

It is the whole first byte (right to left) and the second one of which all bits except the first one are set to 0because useless in this context. First bit (right to left) tells if digital channel 0 (D0) is enabled (bit to 1) ordisabled (bit to 0), second bit is for D1 and so on until ninth bit which is for D8

contains_analogTrue if at least one analog channel is enabled, False otherwise

contains_digitalTrue if at least one digital channel is enabled, False otherwise

is_analog_enabled(pin)Tells if a given analog pin is enabled or not

Parameters pin (int) – analog pin number

Returns True if the given analog pin is enabled, False otherwise

Return type boolean

3.2. Response 9


is_digital_enabled(pin)Tells if a given digital pin is enabled or not

Parameters pin (int) – digital pin number

Returns True if the given digital pin is enabled, False otherwise

Return type boolean

is_digital_on(index, pin)Tells if a given digital pin is on or not in a sample

Parameters

• index (int) – index of the sample

• pin (int) – digital pin number

Returns True if the given digital pin is on in the sample, False otherwise

Return type boolean

get_analog(index, pin)Gives the analog value of a pin in a sample

Parameters


• pin (int) – analog pin number

Returns analog pin value

Return type int

class hachi.response.Rx16IoSampleResponse(frame)IO sample response using 16-bits addressing

Frame example: 7E 00 14 83 7D 84 23 01 02 14 88 00 80 00 8F 03 ED 00 08 02 4C 00 0C 58




sample_countSample count, immediatly following the options

analog_maskAnalog mask, immediatly following the sample_count

It is the whole byte of which first and last bit are set to 0 because useless in this context. Second bit (rightto left) tells if analog channel 0 (A0) is enabled (bit to 1) or disabled (bit to 0), third bit is for A1 and soon until seventh bit which is for A5

digital_maskDigital mask, on 2 bytes including the analog_mask byte

It is the whole first byte (right to left) and the second one of which all bits except the first one are set to 0because useless in this context. First bit (right to left) tells if digital channel 0 (D0) is enabled (bit to 1) ordisabled (bit to 0), second bit is for D1 and so on until ninth bit which is for D8








Return type boolean




Return type boolean

is_digital_on(index, pin)Tells if a given digital pin is on or not in a sample

Parameters


• pin (int) – digital pin number

Returns True if the given digital pin is on in the sample, False otherwise

Return type boolean

get_analog(index, pin)Gives the analog value of a pin in a sample

Parameters


• pin (int) – analog pin number


Return type int

class hachi.response.AtResponse(frame)Response to a AtRequest

Frame example: 7E 00 07 88 52 4D 59 00 00 00 7F

frame_idFrame Id, first byte of the id_data

commandCommand, on 2 bytes immediately following the frame_id

statusStatus, immediately following the command

valueValue, all bytes following the status until the end of the id_data

3.2. Response 11


class hachi.response.TxStatusResponse(frame)Status response emitted by the module after a Tx64Request or a Tx16Request

Frame example: 7E 00 03 89 2A 74 D8


statusStatus, immediately following the frame_id

class hachi.response.ModemStatusResponse(frame)Modem status response

Frame example: 7E 00 02 8A 06 6F

statusStatus, first byte of the id_data

class hachi.response.ZBTxStatusResponse(frame)Status response emitted by the module after a ZBTxRequest or a ZBExplicitTxRequest

Frame example: 7E 00 07 8B 01 7D 84 00 00 01 71


destination_addressDestination address, on 2 bytes immediately following the frame_id

retry_countRetry count, immediately following the destination_address

delivery_statusDelivery status, immediately following the retry_count

discovery_statusDiscovery status, immediately following the delivery_status

class hachi.response.ZBRxResponse(frame)Response to a ZBTxRequest

Frame example: 7E 00 12 90 00 13 A2 00 40 52 2B AA 7D 84 01 52 78 44 61 74 61 0D

source_address_6464-bits source address, first 8 bytes of the id_data

source_address_1616-bits source address, on 2 bytes immediately following the source_address_64

optionsOptions, immediately following the source_address_16


class hachi.response.ZBExplicitRxResponse(frame)Response to a ZBExplicitTxRequest

Frame example: 7E 00 18 91 00 13 A2 00 40 52 2B AA 7D 84 E0 E0 22 11 C1 05 02 52 78 44 61 74 61 52





source_endpointSource endpoint, immediately following the source_address_16

destination_endpointDestination endpoint, immediately following the source_endpoint

cluster_idCluster id, on 2 bytes immediately following the destination_endpoint

profile_idProfile id, on 2 bytes immediately following the cluster_id

optionsOptions, immediately following the profile_id


class hachi.response.ZBIoSampleResponse(frame)IO sample response

Frame example: 7E 00 14 92 00 13 A2 00 40 52 2B AA 7D 84 01 01 00 1C 02 00 14 02 25 F5



optionsOptions, immediately following the source_address_16

sample_countSample count, immediately following the options

digital_maskDigital mask, on 2 bytes, immediately following the sample_count

analog_maskAnalog mask, immediately following the digital_mask






Return type boolean




3.2. Response 13


Return type boolean

is_digital_on(pin)Tells if a given digital pin is on or not


Returns True if the given digital pin is on, False otherwise

Return type boolean

get_analog(pin)Gives the analog value of a pin



Return type int

supply_voltageGives the supply voltage in mV

Returns supply voltage in mV if available or None

Return type int or None

class hachi.response.RemoteAtResponse(frame)Response to a RemoteAtRequest

Frame example: 7E 00 13 97 55 00 13 A2 00 40 52 2B AA 7D 84 53 4C 00 40 52 2B AA F0


source_address_6464-bits source address, on 8 bytes immediately following the frame_id


commandCommand, on two bytes immediately following the source_address_16

statusStatus, immediately following the command

dataData, all bytes following the status until the end of the id_data if any None otherwise

3.2.2 Map

hachi.response.RESPONSE_MAPMapping from Response API IDs to XBeeResponse

3.2.3 Utilities

hachi.response.bitcount(number)Count the number of bits to 1 in a number

For example:



>>> bitcount(0b10110010)4>>> bitcount(0b0100)1

Parameters number (int) – number on which to count the positive bits

Returns the number of positive bits

Return type int

3.3 Request

3.3.1 Requests

hachi.request.FRAME_ID_DEFAULT = 1Frame id used by default. It is non-zero to trigger a status response

hachi.request.TRANSMIT_OPTION_DEFAULT = 0Transmit option used by default.

class hachi.request.XBeeRequestBase class for all XBee requests

The XBeeRequest provides helpers to access to the raw API frame. Unless specified, the type of attributes isint.

api_id = NoneAPI ID

Subclasses must implement this and return the corresponding API ID

lengthComputed length

id_dataAPI ID-specific raw data, bytes between the api_id and the checksum

Subclasses must implement this

Type bytearray

checksumComputed checksum

frameComputed frame

class hachi.request.Tx64Request(data, destination_address=0, options=0, frame_id=1)Tx Request using 64-bit addressing

frame_id = NoneFrame id

destination_address = None64-bit destination address

options = NoneOptions

3.3. Request 15


data = NoneData

Type bytearray or bytes

class hachi.request.Tx16Request(data, destination_address, options=0, frame_id=1)Tx Request using 16-bit addressing


destination_address = None16-bit destination address


data = NoneData


class hachi.request.AtRequest(command, parameter=None, frame_id=1)At Request


command = NoneCommand

Type bytes

parameter = NoneParameter value

Set to None to query the register

Type None or bytearray or bytes

class hachi.request.AtQueueRequest(command, parameter=None, frame_id=1)At Queue Request



Type bytes




class hachi.request.ZBTxRequest(data, destination_address_64=0, destination_address_16=65534,broadcast_radius=0, options=0, frame_id=1)

ZB Tx Request




destination_address_64 = None64-bit destination address


broadcast_radius = NoneBroadcast radius


data = NoneData


class hachi.request.ZBExplicitTxRequest(data, destination_address_64, source_endpoint, des-tination_endpoint, cluster_id, profile_id, destina-tion_address_16=65534, broadcast_radius=0, op-tions=0, frame_id=1)

ZB Explicit Tx Request




source_endpoint = NoneSource endpoint

destination_endpoint = NoneDestination endpoint

cluster_id = NoneCluster id

profile_id = NoneProfile id

broadcast_radius = NoneBroadcast radius


data = NoneData


class hachi.request.RemoteAtRequest(command, destination_address_64, parameter=None, desti-nation_address_16=65534, options=2, frame_id=1)

Remote At Request



3.3. Request 17





Type bytes




3.3.2 Map

hachi.request.REQUEST_MAPMapping from Request API IDs to XBeeRequest

3.4 Constants

3.4.1 Special bytes

hachi.const.FRAME_DELIMITER = 126Frame delimiter byte

hachi.const.ESCAPE = 125Escape byte

hachi.const.XON = 17XON byte

hachi.const.XOFF = 19XOFF byte

3.4.2 API IDs

Request API IDs

hachi.const.TX_64_REQUEST = 0API ID for Tx64Request

hachi.const.TX_16_REQUEST = 1API ID for Tx16Request

hachi.const.AT_REQUEST = 8API ID for AtRequest

hachi.const.AT_QUEUE_REQUEST = 9API ID for AtQueueRequest

hachi.const.ZB_TX_REQUEST = 16API ID for ZBTxRequest



hachi.const.ZB_EXPLICIT_TX_REQUEST = 17API ID for ZBExplicitTxRequest

hachi.const.REMOTE_AT_REQUEST = 23API ID for RemoteAtRequest

Response API IDs

hachi.const.RX_64_RESPONSE = 128API ID for Rx64Response

hachi.const.RX_16_RESPONSE = 129API ID for Rx16Response

hachi.const.RX_64_IO_RESPONSE = 130API ID for Rx64IoSampleResponse

hachi.const.RX_16_IO_RESPONSE = 131API ID for Rx16IoSampleResponse

hachi.const.AT_RESPONSE = 136API ID for AtResponse

hachi.const.TX_STATUS_RESPONSE = 137API ID for TxStatusResponse

hachi.const.MODEM_STATUS_RESPONSE = 138API ID for ModemStatusResponse

hachi.const.ZB_TX_STATUS_RESPONSE = 139API ID for ZBTxStatusResponse

hachi.const.ZB_RX_RESPONSE = 144API ID for ZBRxResponse

hachi.const.ZB_EXPLICIT_RX_RESPONSE = 145API ID for ZBExplicitRxResponse

hachi.const.ZB_IO_SAMPLE_RESPONSE = 146API ID for ZBIoSampleResponse

hachi.const.REMOTE_AT_RESPONSE = 151API ID for RemoteAtResponse

3.4.3 Special frame ids

hachi.const.FRAME_ID_NO_RESPONSE = 0Frame id that disables status responses

3.4.4 Special addresses

hachi.const.ADDRESS_16_USE_64_BIT_ADDRESSING = 65534Use 64-bit addressing 16-bit address. Applies to Tx16Request

hachi.const.ADDRESS_16_BROADCAST = 65535Broadcast 16-bit address

hachi.const.ADDRESS_64_COORDINATOR = 0Coordinator 64-bit address

3.4. Constants 19


hachi.const.ADDRESS_64_BROADCAST = 65535Broadcast 64-bit address

hachi.const.ADDRESS_64_UNKNOWN = 18446744073709551615LUnknown 64-bit address

3.4.5 Special broadcast radius

hachi.const.BROADCAST_RADIUS_MAX_HOPS = 0Maximum hops

3.4.6 Transmit options

hachi.const.TRANSMIT_OPTION_DISABLE_ACKNOWLEDGEMENT = 1Disable acknowledgement. Applies to Tx64Request and Tx16Request

hachi.const.TRANSMIT_OPTION_BROADCAST_PACKET = 4Send packet with broadcast pan id. Applies to Tx64Request and Tx16Request

hachi.const.TRANSMIT_OPTION_APPLY_CHANGES = 2Apply changes. Applies to RemoteAtRequest

hachi.const.TRANSMIT_OPTION_DISABLE_RETRIES_AND_ROUTE_REPAIR = 1Disable retries and route repair. Applies to ZBTxRequest and ZBExplicitTxRequest

hachi.const.TRANSMIT_OPTION_ENABLE_APS_ENCRYPTION = 32Enable APS encryption. Applies to ZBTxRequest and ZBExplicitTxRequest

hachi.const.TRANSMIT_OPTION_USE_EXTENDED_TRANSMISSION_TIMEOUT = 64Use extended transmission timeout. Applies to ZBTxRequest and ZBExplicitTxRequest

3.4.7 Receive options

hachi.const.RECEIVE_OPTION_ADDRESS_BROADCAST = 1Address broadcast. Applies to Rx64Response and Rx16Response

hachi.const.RECEIVE_OPTION_PAN_BROADCAST = 2PAN broadcast. Applies to Rx64Response and Rx16Response

hachi.const.RECEIVE_OPTION_PACKET_ACKNOWLEDGED = 1Packet acknowledged. Applies to ZBRxResponse and ZBExplicitRxResponse

hachi.const.RECEIVE_OPTION_PACKET_BROADCAST = 2Packet was a broadcast packet. Applies to ZBRxResponse and ZBExplicitRxResponse

hachi.const.RECEIVE_OPTION_PACKET_ENCRYPTED_WITH_APS = 32Packet encrypted with APS encryption. Applies to ZBRxResponse and ZBExplicitRxResponse

hachi.const.RECEIVE_OPTION_PACKET_FROM_END_DEVICE = 64Packet was sent from an end device (if known). Applies to ZBRxResponse and ZBExplicitRxResponse

3.4.8 Transmit statuses

hachi.const.STATUS_SUCCESS = 0Success. Applies to TxStatusResponse and ZBTxStatusResponse



hachi.const.STATUS_MAC_ACK_FAILURE = 1MAC ACK failure. Applies to TxStatusResponse and ZBTxStatusResponse

hachi.const.STATUS_CCA_FAILURE = 2CCA failure. Applies to TxStatusResponse and ZBTxStatusResponse

hachi.const.STATUS_PURGED = 3Purged. Applies to TxStatusResponse

hachi.const.STATUS_INVALID_DESTINATION_ENDPOINT = 21Invalid destination endpoint. Applies to ZBTxStatusResponse

hachi.const.STATUS_NETWORK_ACK_FAILURE = 33Network ACK failure. Applies to ZBTxStatusResponse

hachi.const.STATUS_NOT_JOINED_TO_NETWORK = 34Not joined to network. Applies to ZBTxStatusResponse

hachi.const.STATUS_SELF_ADDRESSED = 35Self-addressed. Applies to ZBTxStatusResponse

hachi.const.STATUS_ADDRESS_NOT_FOUND = 36Address not found. Applies to ZBTxStatusResponse

hachi.const.STATUS_ROUTE_NOT_FOUND = 37Route not found. Applies to ZBTxStatusResponse

hachi.const.STATUS_NEIGHBOR_FAILURE = 38Broadcast source failed to hear a neighbor relay relay the message. Applies to ZBTxStatusResponse

hachi.const.STATUS_INVALID_BINDING_TABLE_INDEX = 43Invalid binding table index. Applies to ZBTxStatusResponse

hachi.const.STATUS_RESOURCE_ERROR = 44Resource error lack of free buffers, timers, etc. Applies to ZBTxStatusResponse

hachi.const.STATUS_ATTEMPTED_BROADCAST_WITH_APS = 45Attempted broadcast with APS transmission. Applies to ZBTxStatusResponse

hachi.const.STATUS_ATTEMPTED_UNICAST_APS = 46Attempted unicast with APS transmission but EE=0. Applies to ZBTxStatusResponse

hachi.const.STATUS_RESOURCE_ERROR_2 = 50Resource error lack of free buffers, timers, etc. Applies to ZBTxStatusResponse

hachi.const.STATUS_DATA_PAYLOAD_TOO_LARGE = 116Data payload too large. Applies to ZBTxStatusResponse

hachi.const.STATUS_INDIRECT_MESSAGE_UNREQUESTED = 117Indirect message unrequested. Applies to ZBTxStatusResponse

3.4.9 Discovery statuses

hachi.const.DISCOVERY_STATUS_NO_OVERHEAD = 0No overhead discovery. Applies to ZBTxStatusResponse

hachi.const.DISCOVERY_STATUS_ADDRESS = 1Address discovery. Applies to ZBTxStatusResponse

hachi.const.DISCOVERY_STATUS_ROUTE = 2Route discovery. Applies to ZBTxStatusResponse

3.4. Constants 21


hachi.const.DISCOVERY_STATUS_ADDRESS_AND_ROUTE = 3Address and route discovery. Applies to ZBTxStatusResponse

hachi.const.DISCOVERY_STATUS_EXTENDED_TIMEOUT = 64Extended timeout discovery. Applies to ZBTxStatusResponse

3.4.10 Command statuses

hachi.const.COMMAND_STATUS_OK = 0OK. Applies to AtResponse and RemoteAtResponse

hachi.const.COMMAND_STATUS_ERROR = 1Error. Applies to AtResponse and RemoteAtResponse

hachi.const.COMMAND_STATUS_INVALID_COMMAND = 2Invalid command. Applies to AtResponse and RemoteAtResponse

hachi.const.COMMAND_STATUS_INVALID_PARAMETER = 3Invalid parameter. Applies to AtResponse and RemoteAtResponse

hachi.const.COMMAND_STATUS_NO_RESPONSE = 4No response. Applies to RemoteAtResponse

3.4.11 Modem statuses

hachi.const.MODEM_STATUS_HARDWARE_RESET = 0Hardware reset

hachi.const.MODEM_STATUS_WATCHDOG_TIMER_RESET = 1Watchdog timer reset

hachi.const.MODEM_STATUS_ASSOCIATED = 2Associated

hachi.const.MODEM_STATUS_DISASSOCIATED = 3Disassociated

hachi.const.MODEM_STATUS_SYNCHRONIZATION_LOST = 4Synchronization lost

hachi.const.MODEM_STATUS_COORDINATOR_REALIGNMENT = 5Coordinator realignment

hachi.const.MODEM_STATUS_COORDINATOR_STARTED = 6Coordinator started

hachi.const.MODEM_STATUS_NETWORK_SECURITY_KEY_UPDATED = 7Network security key updated

hachi.const.MODEM_STATUS_VOLTAGE_SUPPLY_LIMIT_EXCEEDED = 13Voltage supply limit exceeded

hachi.const.MODEM_STATUS_MODEM_CONFIGURATION_CHANGED_WHILE_JOINING = 17Modem configuration changed while join in progress

hachi.const.MODEM_STATUS_STACK_ERROR_MIN = 128Stack error minimum



3.5 Exceptions

class hachi.exceptions.HachiErrorBase class for all exceptions in hachi

class hachi.exceptions.TimeoutTimeout

3.6 Serial

class hachi.serial.XBeeSerial(port, baudrate=9600)XBee parser serial implementation with pySerial

Parameters

• port (str or int) – serial port name or number. See pySerial’s documentation for more details

• baudrate (int) – serial baudrate. See pySerial’s documentation for more details

read_response(timeout=None)Read response from serial

Parameters timeout (None or int or float) – timeout in seconds. See pySerial’s documentationfor more details

Raise Timeout when timeout is exceeded

send(request)Send a XBeeRequest through serial

Parameters request (XBeeRequest) – the request to send

close()Close the serial port

3.7 Twisted

class hachi.twisted.XBeeProtocolXBee parser twisted implementation

responseReceived(response)Callback called whenever a XBeeResponse is received

Subclasses must implement this

Parameters response (XBeeResponse) – the received response

3.5. Exceptions 23

http://pyserial.sourceforge.net/



CHAPTER 4

History

4.1 0.5.1

release date: 2014-04-10

• Add a close method to XBeeSerial

4.2 0.5


• Add supply_voltage property to ZBIoSampleResponse

• Add a requirements file

• Add extras in setup

• Improve coverage

4.3 0.4


• Remove frame id attribute in ZBRxResponse

4.4 0.3


• Python 2.7.3 fixes

4.5 0.2


• Python 3 fixes

25


4.6 0.1


• First release

26 Chapter 4. History

Python Module Index

hhachi.const, ??hachi.core, ??hachi.exceptions, ??hachi.request, ??hachi.response, ??hachi.serial, ??hachi.twisted, ??

27

hachi documentation - media.readthedocs.org filehachi documentation, release 0.5.1 class...

Documents