mirage.libs.zigbee_utils package

Submodules

mirage.libs.zigbee_utils.rzusbstick module

class mirage.libs.zigbee_utils.rzusbstick.RZUSBStickDevice(interface)

Bases: mirage.libs.wireless_utils.device.Device

This device allows to communicate with a RZUSBstick in order to interact with the Zigbee protocol. The corresponding interfaces are : rzusbstickX (e.g. “rzusbstick0”)

The following capabilities are actually supported :

Capability

Available ?

SNIFFING

yes

INJECTING

yes

COMMUNICATING_AS_COORDINATOR

yes

COMMUNICATING_AS_ROUTER

yes

COMMUNICATING_AS_END_DEVICE

yes

JAMMING

yes

Warning

Some features provided by this hardware seems unstable :
  • A small amount of time is required to switch from TX to RX, so some frames may be missing

  • The jamming feature seems to send a very short signal which is not strong and long enough to jam a Zigbee channel

I’m not sure if the problem is linked to my hardware or if the Killerbee firmare is buggy.

close()

This method closes the device.

disableJamming()

This method disables the jamming mode of the current RZUSBStick device.

Example
>>> device.disableJamming()

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

enableJamming()

This method enables the jamming mode of the current RZUSBStick device.

Example
>>> device.enableJamming()

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getChannel()

This method returns the channel actually in use.

Returns

channel in use

Return type

int

Example
>>> device.getChannel()
11
>>> device.setChannel(15)
>>> device.getChannel()
15

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getDeviceIndex()

This method returns the index of the current RZUSBStick device.

Returns

device’s index

Return type

int

Example
>>> device.getDeviceIndex()
0

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getFirmwareVersion()

This method returns the firmware version of the current RZUSBStick device.

Returns

device’s firmware version

Return type

str

Example
>>> device.getSerial()
'KILLERB001'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getMode()

This method returns the current mode in use (RZUSBStick device can be set in two modes: NORMAL, JAMMING)

Returns

current mode in use

Return type

str

Example
>>> device.getMode()
'NORMAL'
>>> device.enableJamming()
>>> device.getMode()
'JAMMING'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getSerial()

This method returns the serial number of the current RZUSBStick device.

Returns

device’s serial number

Return type

str

Example
>>> device.getSerial()
'FFFFFFFFFFFF'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

init()

This method initializes the device.

isUp()

This method allows to check if the device is initialized and available for use.

Returns

boolean indicating if the device is up

Return type

bool

recv()

This method receives some datas. If no data is available, this method returns None.

Parameters

data – raw representation of the received data

classmethod resetRZUSBStick(index=0)
send(packet)

This method sends some datas.

Parameters

data – raw representation of the data to send

setChannel(channel)

This method changes the channel actually in use by the provided channel.

Parameters

channel (int) – new channel

Example
>>> device.getChannel()
11
>>> device.setChannel(15)
>>> device.getChannel()
15

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

sharedMethods = ['getChannel', 'setChannel', 'enableJamming', 'disableJamming', 'getMode', 'getFirmwareVersion', 'getSerial', 'getDeviceIndex']

mirage.libs.zigbee_utils.constants module

This module contains some constants that are used by the Zigbee stack.

mirage.libs.zigbee_utils.pcap module

class mirage.libs.zigbee_utils.pcap.ZigbeePCAPDevice(interface)

Bases: mirage.libs.wireless_utils.pcapDevice.PCAPDevice

This device allows to communicate with a PCAP file in order to write and read Zigbee packets.

The corresponding interfaces are : <filename>.pcap (e.g. “out.pcap”)

  • If the file exists, the ZigbeePCAPDevice is in read mode, and the corresponding receiver is able to use it as a classic Zigbee sniffer.

  • If the file doesn’t exist, the ZigbeePCAPDevice is in write mode, and the corresponding emitter is able to write packets in the file.

The following capabilities are actually supported :

Capability

Available ?

SNIFFING

yes

INJECTING

yes

COMMUNICATING_AS_COORDINATOR

no

COMMUNICATING_AS_ROUTER

no

COMMUNICATING_AS_END_DEVICE

no

JAMMING

no

Warning

This PCAP Device uses the DLT 195.

DLT = 195
SCAPY_LAYER

alias of scapy.layers.dot15d4.Dot15d4

generateStream()

This method generates a stream (i.e. a list of packets with the right inter frame spacing) from the PCAP file.

Returns

stream of packets

Return type

list

Example
>>> stream = device.generateStream()
>>> device2.sendp(*stream)

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getChannel()

This method allows to simulate the getChannel behaviour of a normal sniffer.

Returns

integer indicating an unknown channel (-1)

Return type

int

Example
>>> device.getChannel()
-1

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

init()

This method initializes the PCAP file, by checking the header (if the Device is in reading mode) or by adding the header (if the Device is in writing mode).

send(packet)

This method writes a packet synchronously into the PCAP file.

Parameters

packet (bytes or scapy frame (if SCAPY_LAYER is not None)) – packet to write

setChannel(channel)

This method allows to simulate the setChannel behaviour of a normal sniffer.

Parameters

channel (int) – channel to set

Example
>>> device.getChannel()
-1

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

sharedMethods = ['generateStream', 'setChannel', 'getChannel', 'getMode']

mirage.libs.zigbee_utils.helpers module

mirage.libs.zigbee_utils.helpers.addressToString(address)

This function converts a Zigbee address (as integer) to a printable string.

Parameters

address (int) – integer indicating the address to convert

Returns

printable string of the address

Return type

str

Example
>>> addressToString(0x1234)
'0x1234'
>>> addressToString(0x1122334455667788)
'11:22:33:44:55:66:77:88'
mirage.libs.zigbee_utils.helpers.channelToFrequency(channel)

This function converts a Zigbee channel to the corresponding frequency.

Parameters

channel (int) – Zigbee channel to convert

Returns

corresponding frequency (MHz)

Return type

int

Example
>>> channelToFrequency(11)
2405
>>> channelToFrequency(14)
2420
mirage.libs.zigbee_utils.helpers.convertAddress(address)

This function is used to convert a Zigbee address to a standard format (integer).

Parameters

address (str or int or bytes) – address to convert

Returns

address in a standard format (integer)

Return type

int

Example
>>> convertAddress(0x1234)
4660
>>> convertAddress(bytes.fromhex("1122334455667788"))
1234605616436508552
mirage.libs.zigbee_utils.helpers.fcs(data)

This function calculates the 16 bits FCS corresponding to the data provided.

Parameters

data (bytes) – packet’s payload

Example
>>> data=bytes.fromhex("2188013412ffff000000001200610d0a")
>>> fcs(data).hex()
'0b29'
mirage.libs.zigbee_utils.helpers.frequencyToChannel(frequency)

This function converts a frequency to the corresponding Zigbee channel.

Parameters

frequency (int) – frequency to convert (MHz)

Returns

channel associated to the provided frequency

Return type

int

Example
>>> frequencyToChannel(2405)
11
>>> frequencyToChannel(2420)
14

mirage.libs.zigbee_utils.packets module

class mirage.libs.zigbee_utils.packets.ZigbeeAcknowledgment(sequenceNumber=1, destAddr=65535, destPanID=65535, srcAddr=0, srcPanID=4660)

Bases: mirage.libs.zigbee_utils.packets.ZigbeePacket

Mirage Zigbee Packet - Acknowledgment

Parameters
  • sequenceNumber (int) – sequence number of the packet

  • destAddr (int) – destination address included in the Packet

  • destPanID (int) – destination PanID included in the Packet

  • srcAddr (int) – source address included in the Packet

  • srcPanID (int) – source PanID included in the Packet

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.zigbee_utils.packets.ZigbeeApplicationData(sequenceNumber=1, destAddr=65535, destPanID=65535, srcAddr=0, srcPanID=4660, data=b'')

Bases: mirage.libs.zigbee_utils.packets.ZigbeePacket

Mirage Zigbee Packet - Application Data

Parameters
  • sequenceNumber (int) – sequence number of the packet

  • destAddr (int) – destination address included in the Packet

  • destPanID (int) – destination PanID included in the Packet

  • srcAddr (int) – source address included in the Packet

  • srcPanID (int) – source PanID included in the Packet

  • data (bytes) – application data included in the Packet

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.zigbee_utils.packets.ZigbeeApplicationEncryptedData(sequenceNumber=1, destAddr=65535, destPanID=65535, srcAddr=0, frameCounter=0, keyType=None, securityLevel=None, source=None, keySequenceNumber=None, data=b'', mic=b'')

Bases: mirage.libs.zigbee_utils.packets.ZigbeePacket

Mirage Zigbee Packet - Application Encrypted Data

Parameters
  • sequenceNumber (int) – sequence number of the packet

  • destAddr (int) – destination address included in the Packet

  • destPanID (int) – destination PanID included in the Packet

  • srcAddr (int) – source address included in the Packet

  • frameCounter (int) – frame counter

  • keyType (int) – field indicating the key type (0: Data Key, 1: Network Key, 2: Key Transport Key, 3: Key load Key)

  • securityLevel (int) – field indicating the security level (0: none, 1: MIC-32, 2: MIC-64, 3: MIC-128, 4: ENC, 5: ENC-MIC-32, 6: ENC-MIC-64, 7: ENC-MIC-128)

  • source (int) – source address

  • keySequenceNumber (int) – sequence number associated to the key

  • data (bytes) – application data included in the Packet (encrypted)

  • mic (bytes) – message integrity check

keyTypes = ['Data Key', 'Network Key', 'Key transport Key', 'Key load Key']
securityLevels = ['none', 'MIC-32', 'MIC-64', 'MIC-128', 'ENC', 'ENC-MIC-32', 'ENC-MIC-64', 'ENC-MIC-128']
toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.zigbee_utils.packets.ZigbeeAssociationRequest(sequenceNumber=1, destAddr=65535, destPanID=65535, srcAddr=0, srcPanID=65535, allocateAddress=False, securityCapability=False, receiverOnWhenIdle=False, powerSource=False, deviceType=False, alternatePanCoordinator=False)

Bases: mirage.libs.zigbee_utils.packets.ZigbeePacket

Mirage Zigbee Packet - Association Request

Parameters
  • sequenceNumber (int) – sequence number of the packet

  • destAddr (int) – destination address included in the Packet

  • destPanID (int) – destination PanID included in the Packet

  • srcAddr (int) – source address included in the Packet

  • srcPanID (int) – source PanID included in the Packet

  • allocateAddress (bool) – boolean indicating if an address allocation is required

  • securityCapability (bool) – boolean indicating if the device has a security capability

  • receiverOnWhenIdle (bool) – boolean indicating if the receiver is on when the device is in idle mode

  • powerSource (bool) – boolean indicating if the device has a power source

  • deviceType (bool) – boolean indicating the device type

  • alternatePanCoordinator (bool) – boolean indicating if the emitter is an alternate PAN coordinator

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.zigbee_utils.packets.ZigbeeAssociationResponse(sequenceNumber=1, destAddr=65535, destPanID=65535, srcAddr=0, srcPanID=4660, assignedAddr=65535, status=None)

Bases: mirage.libs.zigbee_utils.packets.ZigbeePacket

Mirage Zigbee Packet - Association Response

Parameters
  • sequenceNumber (int) – sequence number of the packet

  • destAddr (int) – destination address included in the Packet

  • destPanID (int) – destination PanID included in the Packet

  • srcAddr (int) – source address included in the Packet

  • srcPanID (int) – source PanID included in the Packet

  • assignedAddr (int) – assigned address

  • status (int) – integer indicating the status of association (0: successful, 1: PAN at capacity, 2: PAN access denied)

statusMessage = ['successful', 'PAN at capacity', 'PAN access denied']
toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.zigbee_utils.packets.ZigbeeBeacon(sequenceNumber=1, srcAddr=0, srcPanID=65535, assocPermit=False, coordinator=False, payload=False, routerCapacity=None, endDeviceCapacity=None, extendedPanID=None)

Bases: mirage.libs.zigbee_utils.packets.ZigbeePacket

Mirage Zigbee Packet - Beacon

Parameters
  • sequenceNumber (int) – sequence number of the packet

  • srcAddr (int) – source address included in the Packet

  • srcPanID (int) – source PanID included in the Packet

  • assocPermit (bool) – boolean indicating if the association is permitted

  • coordinator (bool) – boolean indicating if the emitter of the beacon is a coordinator

  • payload (bool) – boolean indicating if the packet includes a zigbee payload

  • routerCapacity (bool) – boolean indicating the router capacity

  • endDeviceCapacity (bool) – boolean indicating the end device capacity

  • extendedPanID (int) – extended Pan ID

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.zigbee_utils.packets.ZigbeeBeaconRequest(sequenceNumber=1, destAddr=65535, destPanID=65535)

Bases: mirage.libs.zigbee_utils.packets.ZigbeePacket

Mirage Zigbee Packet - Beacon Request

Parameters
  • sequenceNumber (int) – sequence number of the packet

  • destAddr (int) – destination address included in the Packet

  • destPanID (int) – destination PanID included in the Packet

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.zigbee_utils.packets.ZigbeeDataRequest(sequenceNumber=1, destAddr=65535, srcAddr=0, destPanID=4660, srcPanID=0)

Bases: mirage.libs.zigbee_utils.packets.ZigbeePacket

Mirage Zigbee Packet - Data Request

Parameters
  • sequenceNumber (int) – sequence number of the packet

  • destAddr (int) – destination address included in the Packet

  • destPanID (int) – destination PanID included in the Packet

  • srcAddr (int) – source address included in the Packet

  • srcPanID (int) – source PanID included in the Packet

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.zigbee_utils.packets.ZigbeeDisassociationNotification(sequenceNumber=1, destAddr=65535, destPanID=65535, srcAddr=0, srcPanID=4660, assignedAddr=65535, reason=None)

Bases: mirage.libs.zigbee_utils.packets.ZigbeePacket

Mirage Zigbee Packet - Disassociation Notification

Parameters
  • sequenceNumber (int) – sequence number of the packet

  • destAddr (int) – destination address included in the Packet

  • destPanID (int) – destination PanID included in the Packet

  • srcAddr (int) – source address included in the Packet

  • srcPanID (int) – source PanID included in the Packet

  • assignedAddr (int) – assigned address

  • reason (int) – integer indicating the disassociation reason (1: Coordinator requests device to leave, 2: Device requests to leave)

reasonMessage = ['reserved', 'Coordinator requests device to leave', 'Device requests to leave']
toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.zigbee_utils.packets.ZigbeePacket(sequenceNumber=1, data=b'')

Bases: mirage.libs.wireless_utils.packets.Packet

Mirage Zigbee Packet

Parameters
  • sequenceNumber (int) – sequence number of the packet

  • data (bytes) – data associated to the Packet

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.zigbee_utils.packets.ZigbeeSniffingParameters(rssi=None, channel=None, frequency=None, validCrc=False, linkQualityIndicator=None)

Bases: mirage.libs.wireless_utils.packets.AdditionalInformations

This class allows to attach some sniffer’s data to a Mirage Zigbee Packet, such as RSSI, valid CRC,link quality indicator or channel. If the frequency is provided, the corresponding channel is automatically calculated.

Parameters
  • rssi (float) – Received Signal Strength Indication

  • channel (int) – channel of the received packet

  • frequency (float) – frequency of the received packet

  • validCrc (bool) – boolean indicating if the CRC is valid or not

  • linkQualityIndicator (int) – integer indicating the link quality indicator

toString()
class mirage.libs.zigbee_utils.packets.ZigbeeXBeeData(sequenceNumber=1, destAddr=65535, destPanID=65535, srcAddr=0, srcPanID=4660, counter=0, unknown=0, data=b'')

Bases: mirage.libs.zigbee_utils.packets.ZigbeePacket

Mirage Zigbee Packet - XBee Data

Parameters
  • sequenceNumber (int) – sequence number of the packet

  • destAddr (int) – destination address included in the Packet

  • destPanID (int) – destination PanID included in the Packet

  • srcAddr (int) – source address included in the Packet

  • srcPanID (int) – source PanID included in the Packet

  • counter (int) – XBee counter

  • unknown (int) – XBee unknown field

  • data (bytes) – XBee data

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

mirage.libs.zigbee_utils.scapy_xbee_layers module

This module contains some scapy definitions for XBee packets.