Difference between revisions of "Wifi and mqtt on the rs9113"

From wiki.emacinc.com
Jump to: navigation, search
Line 116: Line 116:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
This constructor cretes and returns an MQTTClient object. The server connection is not handled by the constructor.
+
*This constructor cretes and returns an MQTTClient object. The server connection is not handled by the constructor. Arguments:
Arguments:
+
**client_id        The client ID sent to the server.
*client_id        The client ID sent to the server.
+
**server            The URL or IP address of the server to connect to.
*server            The URL or IP address of the server to connect to.
+
**port              The port of the server to connect to.
*port              The port of the server to connect to.
+
**user              The username to use, if applicable.
*user              The username to use, if applicable.
+
**password          The password to use, if applicable.
*password          The password to use, if applicable.
+
**keepalive        How long to keep the connection alive, in seconds. 0 disabels the timeout.
*keepalive        How long to keep the connection alive, in seconds. 0 disabels the timeout.
+
**ssl              Determines if SSL is used for the connection.
*ssl              Determines if SSL is used for the connection.
 
 
      
 
      
 
===Methods:===
 
===Methods:===
Line 140: Line 139:
 
MQTT.publish(topic, msg, retain=False, qos=0)
 
MQTT.publish(topic, msg, retain=False, qos=0)
 
</syntaxhighlight>
 
</syntaxhighlight>
Publishes a message to a topic on the connected server.
+
*Publishes a message to a topic on the connected server. Arguments:
Arguments:
+
**topic            Topic to publish to.
*topic            Topic to publish to.
+
**msg              Message to publish.
*msg              Message to publish.
+
**retain            Determines if the message should be retained on reconnect.
*retain            Determines if the message should be retained on reconnect.
+
**qos              The quality of service level to use.
*qos              The quality of service level to use.
 
  
 
<syntaxhighlight lang=python>
 
<syntaxhighlight lang=python>
 
MQTTClient.set_callback(f)
 
MQTTClient.set_callback(f)
 
</syntaxhighlight>
 
</syntaxhighlight>
Sets the callback to be called when a message is retrieved.
+
*Sets the callback to be called when a message is retrieved. Argument:
Argument:
+
**f                The function to be set as the callback.
*f                The function to be set as the callback.
+
*Note: The callback function definition should be in the following format:
Note: The callback function definition should be in the following format:
+
**<syntaxhighlight lang=python>
<syntaxhighlight lang=python>
 
 
def cb(topic, message):
 
def cb(topic, message):
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 161: Line 158:
 
MQTTClient.subscribe(topic, qos=0)
 
MQTTClient.subscribe(topic, qos=0)
 
</syntaxhighlight>
 
</syntaxhighlight>
Subscribes to a topic. A callback must be set by set_callback().
+
*Subscribes to a topic. A callback must be set by set_callback(). Arguments:
Arguments:
+
**topic            Topic to subscribe to.
*topic            Topic to subscribe to.
+
**qos              The quality of service level to use.
*qos              The quality of service level to use.
 
  
 
<syntaxhighlight lang=python>
 
<syntaxhighlight lang=python>

Revision as of 16:03, 6 June 2018

The RS9113 family of modules are ultra-low power radio modules that support wifi, Bluetooth, and ZigBee. Emac has developed driver support for these modules in Micropython.

Wifi

Class RS9113:

This class provides the driver for the RS9113 module through the SPI interface. It is imported from the 'network' module. The following is an example usage:

import network
nic = network.RS9113(pyb.SPI(1), pyb.Pin("A4"), pyb.Pin("D9"), pyb.Pin("D10"))
nic.connect('SSID', 'Password')

Constructor:

network.RS9113(spi, pin_cs, pin_rst, pin_irq)

This constructor creates the RS913 object and initializes the module given the SPI bus and pins. Returns the RS9113 object. Arguments are:

  • spi a Micropython SPI object.
  • pin_cs a Micropython Pin object connected to the RS91113 module's Chip Select pin.
  • pin_rst a Micropython Pin object connected to the RS91113 module's Reset pin.
  • pin_irq a Micropython Pin object connected to the RS91113 module's Interrupt pin.
  • All arguments are initialized by the driver, so there is no need to initialize them manually.

Methods:

RS9113.connect(ssid, key=None,*,security=WPA2, ssl=False, nonblocking=False)
  • Connects to the given SSID and security paramaters. If 'ssl' is set to True, all of the sockets created will be set to use SSL. If 'nonblocking' is set to True, all sockets will use nonblocking functionality.
RS9113.disconnect()
  • Disconnects from the WiFi network.
RS9113.isconnected()
  • Returns a True if connected to a network, False otherwise.
RS9113.sleep()
  • Puts the RS9113 module into deep (disconnected) sleep mode. This function is best called after the board is reset, so re-initializing the class should be done before calling sleep.

nic = network.RS9113(pyb.SPI(1), pyb.Pin("A4"), pyb.Pin("D9"), pyb.Pin("D10")) nic.sleep()

RS9113.ifconfig()
  • Returns a 4-tuple with (ip address, subnet mask, gateway, MAC address). This method requires the module to be successfully connected to a network.
RS9113.macaddr()
  • Returns a string containing the MAC address for the module. The string is colon separated octets without leading '0x.'
RS9113.scan()

Returns a list of 4-tuples with (SSID, RSSI value, security mode, RF channel, BSSID)

RS9113.fwap(ssid=None)



NOTE
Warning: It is not necessary to use this under normal cirumstances.

Intended to be run directly after initialization of the module. This method puts the module into AP mode so that a firmware upgrade is possible. The ssid argument can be supplied to define the name of the access point.

To upgrade the firmware:

  • Run the fwap() method
  • Connect to the access point.
  • In a browser, navigate to the board's IP address.
  • Click on the "Administration" tab.
  • Click "Choose File", select the desired firmware file
  • Click upgrade
  • The REPL will show the progress and will display a completion message when done.
  • Power cycle the board.


Constants:

RS9113.WPA2 RS9113.OPEN Security types to be used in RS9113.scan() and returned in a tuple with RS9113.scan().



NOTE
Information regarding sockets can be found in the Micropython documentation. Once the RS9113 is initialized and

connected, the socket module will use it without prompting.

http://docs.micropython.org/en/v1.8.7/pyboard/library/usocket.html?


MQTT

Class MQTTClient:

This class provides an MQTT interface for use with RS9113 WiFi modems. It is imported from the 'umqtt.robust' or 'umqtt.simple' modules. The following is an example usage:

import network
import umqtt.simple
nic = network.RS9113(pyb.SPI(3), pyb.Pin("I0"), pyb.Pin("E3"), pyb.Pin("E4"))
nic.connect('SSID', 'Password')
client = umqtt.simple.MQTTClient('client id', 'example-server.com', port=1883, user='uname', password='pword', ssl=False)
client.connect()

Constructor:

MQTTClient(client_id, server, port=0, user=None, password=None, keepalive=0, ssl=False)
  • This constructor cretes and returns an MQTTClient object. The server connection is not handled by the constructor. Arguments:
    • client_id The client ID sent to the server.
    • server The URL or IP address of the server to connect to.
    • port The port of the server to connect to.
    • user The username to use, if applicable.
    • password The password to use, if applicable.
    • keepalive How long to keep the connection alive, in seconds. 0 disabels the timeout.
    • ssl Determines if SSL is used for the connection.

Methods:

MQTTClient.connect()
  • Connects to the server provided in the constructor.
MQTTClient.disconnect()
  • Disconnects from the server.
MQTT.publish(topic, msg, retain=False, qos=0)
  • Publishes a message to a topic on the connected server. Arguments:
    • topic Topic to publish to.
    • msg Message to publish.
    • retain Determines if the message should be retained on reconnect.
    • qos The quality of service level to use.
MQTTClient.set_callback(f)
  • Sets the callback to be called when a message is retrieved. Argument:
    • f The function to be set as the callback.
  • Note: The callback function definition should be in the following format:
    • def cb(topic, message):
      
MQTTClient.subscribe(topic, qos=0)
  • Subscribes to a topic. A callback must be set by set_callback(). Arguments:
    • topic Topic to subscribe to.
    • qos The quality of service level to use.
MQTTClient.wait_msg()
  • Wait for a single incoming MQTT message and process it. Subscribed messages are delivered to a callback previously set by .set_callback() method. Other (internal) MQTT messages processed internally.
MQTTClient.check_msg()
  • Checks whether a pending message from server is available. If not, returns immediately with None. Otherwise does the same processing as wait_msg.