.. currentmodule:: pyb .. _pyb.SI446X: 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 ------- .. method:: 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. .. method:: 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. .. method:: SI446X.__str__() Return a string describing the si446x object. .. method:: 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. .. method:: SI446X.mode() Returns the current mode (``NORMAL`` or ``SNIFFER``). .. method:: 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. .. method:: 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`` .. method:: SI446X.rssi() Returns RSSI (in dBm) of the last received packet. .. method:: SI446X.rssi_ack() Returns RSSI (in dBm) of the last received acknowledgment. .. method:: SI446X.shutdown() Shut down the radio chip (call `configure()` to wake it up). Constants --------- .. data:: SI446X.SPEED_0_3 Radio transmission speed 300bps .. data:: SI446X.SPEED_1_2 Radio transmission speed 1.2kbps .. data:: SI446X.SPEED_2_4 Radio transmission speed 1.2kbps .. data:: SI446X.SPEED_4_8 Radio transmission speed 1.2kbps .. data:: SI446X.SPEED_10 Radio transmission speed 1.2kbps .. data:: SI446X.SPEED_38 Radio transmission speed 1.2kbps .. data:: SI446X.SPEED_100 Radio transmission speed 1.2kbps .. data:: SI446X.SPEED_250 Radio transmission speed 1.2kbps .. data:: SI446X.SPEED_500 Radio transmission speed 500kbps .. data:: SI446X.RES_OK Transmission was successful. .. data:: SI446X.RES_BUSY Transmission failed - chip is busy .. data:: SI446X.RES_NACK Transmission failed - acknowledgment has not been received. .. data:: SI446X.RES_INV Transmission failed - hardware error. .. data:: SI446X.NORMAL Normal mode (chip receives only broadcast packets and packets with appropriate destination address. .. data:: SI446X.SNIFFER Sniffer mode (chip receives all packets. No acknowledgment is sent for received packets). .. data:: SI446X.PLAIN Plain transmission mode (send packet over the air, return without waiting for any acknowledgment). .. data:: 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). .. data:: 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).