class SI446X – send/receive data via si446x radio chips

SI446X is the wrapper around si446x driver, that handles all the low-level chip configuration, as well as radio transmission and reception. User only needs to setup the local device address, (optionally) several parameters such as speed, power, channel etc.

Example usage:

import pyb

radio = pyb.SI446X()           #create a si446x object (not configured)
radio.configure(address=42)    #set the local device address to 42 and configure chip

radio.send(43, b'Hello World')  #send a 'Hello...' to a device with the address 43

pkt = radio.recv()             #receive a packet, return immediately if no packet is pending

Constructors

class pyb.SI446X(optional configure args)

Create a new si446x object (internally there is only one). If no arguments are given, the radio chip is not (re)configured. If arguments are present, configure() is called. For a list of accepted argument see the respective function description.

The SPI bus and CS, SDN, etc pins are set during the board image compilation.

Methods

SI446X.configure(address=_default_, speed=SI446X.SPEED_10, channel=0, power=127, backoffs=4, retries=4, key=_inv_, exp_min=1, exp_max=3)

Configure the chip and link layer parameters:

  • address is the local device address and can be [0..65534] (65535 is reserved for the broadcast address). Default value is computed from chip ID

  • speed can be one of

    • SI446X.SPEED_0_3 - 300bps

    • SI446X.SPEED_1_2 - 1.2kbps

    • SI446X.SPEED_2_4 - 2.4kbps

    • SI446X.SPEED_4_8 - 4.8kbps

    • SI446X.SPEED_10 - 10kbps (*the default one)

    • SI446X.SPEED_38 - 38kbps

    • SI446X.SPEED_100 - 100kbps

    • SI446X.SPEED_250 - 250kbps

    • SI446X.SPEED_500 - 500kbps

  • channel is the radio channel and can be [0..255].

  • power is the binary power value in the range of [0..127].

  • backoffs is the number of CCA retries.

  • retries is the number of retries when sending a packet with acknowledgment.

  • key is the cryptographic key (a string of 32 bytes is expected). Default: undefined.

  • exp_min and exp_max are advanced CCA tuning parameters.

Returns: True if the chip has been successfully configured, False otherwise.

SI446X.address([addr])

Get or set the the local device address:

  • With no argument, returns the device current address.

  • With addr given, sets the device address and returns it. addr can be anything that can be converted to an integer.

SI446X.__str__()

Return a string describing the si446x object.

SI446X.sniff()

Puts si446x chip in packet SNIFFER mode - this chip will receive all on-the-air packet in the current network. In order to return to NORMAL mode, call the configure() method.

SI446X.mode()

Returns the current mode (NORMAL or SNIFFER).

SI446X.send(addr, data[, mode=PLAIN, crypt=False])

Send a packet with a data payload to a device with an address addr:

  • mode can be one of:

    • SI446X.PLAIN - just transmit the payload. Do not request or wait for acknowledgment. The function will return once the payload has been sent over the air.

    • SI446X.ACK - transmit the payload and wait for acknowledgment. Re-transmit specified number of times if the acknowledgment is not received.

    • SI446X.ASYNC - send the payload to the radio chip and return. The packet will be transmitted over the air some time later.

  • crypt - payload will be transmitted encrypted if True and as plain text if False (*the default option).

Returns:

  • SI446X.RES_OK if the transmission has been successful.

  • SI446X.RES_BUSY if the chip is busy transmitting or receiving data

  • SI446X.RES_NACK if the acknowledgment has been requested and none has been received

  • SI446X.RES_INV if a hardware related error has occurred.

SI446X.recv([len, timeout=0])

Takes and returns a packet from the internal queue (is one is pending). If len is specified, only a packet that is not longer then len bytes will be returned, otherwise an oversized packet will be dropped from the queue, None returned.

  • timeout - number of milliseconds to wait for a packet to arrive (if none is already pending).

Returns a tuple ([payload, source address, sequence, rssi]) or None

SI446X.rssi()

Returns RSSI (in dBm) of the last received packet.

SI446X.rssi_ack()

Returns RSSI (in dBm) of the last received acknowledgment.

SI446X.shutdown()

Shut down the radio chip (call configure() to wake it up).

Constants

SI446X.SPEED_0_3

Radio transmission speed 300bps

SI446X.SPEED_1_2

Radio transmission speed 1.2kbps

SI446X.SPEED_2_4

Radio transmission speed 1.2kbps

SI446X.SPEED_4_8

Radio transmission speed 1.2kbps

SI446X.SPEED_10

Radio transmission speed 1.2kbps

SI446X.SPEED_38

Radio transmission speed 1.2kbps

SI446X.SPEED_100

Radio transmission speed 1.2kbps

SI446X.SPEED_250

Radio transmission speed 1.2kbps

SI446X.SPEED_500

Radio transmission speed 500kbps

SI446X.RES_OK

Transmission was successful.

SI446X.RES_BUSY

Transmission failed - chip is busy

SI446X.RES_NACK

Transmission failed - acknowledgment has not been received.

SI446X.RES_INV

Transmission failed - hardware error.

SI446X.NORMAL

Normal mode (chip receives only broadcast packets and packets with appropriate destination address.

SI446X.SNIFFER

Sniffer mode (chip receives all packets. No acknowledgment is sent for received packets).

SI446X.PLAIN

Plain transmission mode (send packet over the air, return without waiting for any acknowledgment).

SI446X.ACK

Transmit with acknowledgment (packet is sent over the air and acknowledgment is expected. If none arrives, packet is resent specified number of times).

SI446X.ASYNC

Asynchronous transmission mode (packet is sent to the chip and the function returns. The packet will be transmitted over the air some time later by the chip).