Module Development - wolfen351/public-micropython-iot-platform GitHub Wiki

This is a guide to developing modules for the public-micropython-iot-platform.

Creating a Module

Modules are a way to add functionality to the platform. They are written in micropython and are loaded into the platform at runtime. They can be used to read sensors, control outputs, or communicate with other devices.

Module Structure

A module is a folder under the "modules" directory that contains at least a single .py file. The main .py file contains the micropython code for the module. The file usually contains a single class that inherits from the basic module.

The module contains the following methods:

  • start - This is called a single time when the module is started. Use this to intialise hardware, load config data etc.
  • tick - This is called often, use this to do small amounts of work, like reading sensors or updating outputs.
  • getTelemetry - Use this to return a dictionary of telemetry data that the module wants to send to other modules and interested parties, like MQTT or Home Assistant.
  • processTelemetry - Use this to process telemetry data that has been sent to the module from other modules. For example, if you need to switch a relay when a button is pressed, the button module will use getTelemery to broadcast the fact that the button is pressed. The relay module will use processTelemetry to listen for this and switch the relay.
  • getCommands - Use this to return a list of commands that the module wishes to communicate to ther modules, for example a MQTT module can subscribe to commands and return them processing by other modules.
  • processCommands - Use this to process commands that have been sent to the module from other modules. For example, if you need to switch a relay when a command is received, the relay module will use processCommands to listen for this and switch the relay.
  • getRoutes - Use this to return a dictionary of web routes that the module wishes to expose to the web. For example, a relay module may wish to expose a web route to switch the relay on and off. This allows you to say that a GET to /relay/flip should call the webflip method in this class
  • getIndexFileName - Use this to return the name of the index file that the module wishes to use. This is the part of the homepage user navigates to the web UI.

Here is a full example of a new module:

from modules.basic.basic_module import BasicModule
from serial_log import SerialLog

class example(BasicModule):

def __init__(self):
    pass
 
def start(self):
    BasicModule.start(self)
    self.enabled = self.getPref("example", "enabled", "Y")
    SerialLog.log("Example started")
 
def tick(self):
    SerialLog.log("Do a small amount of work here, the framework calls this often")
 
def getTelemetry(self):
    return { 'operational': True } 
 
def processTelemetry(self, telemetry):
    if 'led' in telemetry:
        if telemetry['led'] == 'on':
            SerialLog.log("Turning on the LED")
        else:
            SerialLog.log("Turning off the LED")
 
def getCommands(self):
    return ['increase/bass']
 
def processCommands(self, commands):
    if 'switch/curtains' in commands:
        SerialLog.log("Switching the curtains")
 
def getRoutes(self):
    return { b"/relay/flip" : self.webFlip }
 
def getIndexFileName(self):
    return { "relay" : "/modules/example/example_index.html" }

# Internal code here

Saving and loading configuration data

Modules can save and load configuration data to the platform. This is useful for storing things like WiFi credentials, MQTT server details, or any other module specific data.

Loading Configuration Data

To load configuration data, call the BasicModule.Start() method. Then you can use self.getPref(<group>, <key>, <defaultvalue>) to access the value from the prefs.json file stored on the board's disk.

This reads the "enabled" key from the "example" document in the prefs.json file. If the key is not found, the default value is returned.

def start(self):
    BasicModule.start(self)
    self.enabled = self.getPref("example", "enabled", "Y")

Saving Configuration Data

To save configuration data, use the self.setPref(<group>,<key>,<value>) method. The data is saved to the prefs.json file on the board's disk.

self.setPref("example", "enabled", "Y")

Logging

The SerialLog class is used to log messages to the serial port and to the web ui log. This is useful for debugging and monitoring the platform.

SerialLog.log("Example started")
⚠️ **GitHub.com Fallback** ⚠️