Custom scripts

Custom scripts are what makes iot-ledmatrix powerful. You can add any gimmick you want by adding an implementation to one of the subfolders of scripts.

Scripts beginning with _ will not be displayed in the app to be manually loaded. Only a custom fragment can load them, because they can only run properly with that custom fragment. Scripts not beginning with _ can be loaded by the user in a default fragment that lists them. Other than that, new custom scripts do not need any configuration effort.

When your new script is requested in the app, it will be loaded and can draw to the led matrix.

How to draw from within the script

Drawing to the matrix is done by using the functions of the canvas supplied with the draw calls. Detailed documentation is available here: Canvas class

Creating a new script

Custom scripts must contain a class that is exactly the name of the source file minus the .py.

For example, if you create a “flashlight” script, the file name would be, and the class name would be flashlight.

You may put your script in a subfolder of the scripts folder. As you might have guessed, that subfolder must also have exactly the name the script class and file has.

For debugging, a simple GUI was implemented. Use the --enable-gui flag to display it.

The class must inherit from CustomScript, which is documented here:

CustomScript class

class CustomScript.CustomScript(canvas, send_object, send_object_to_all, start_script, restart_self, set_frame_period, set_frame_rate, get_connected_clients)[source]

The CustomScript class is the class you want to inherit from to implement a new matrix mode.

In addition to the constructor, there are six methods that will be called by the manager:

They have default implementations, so you only need to override them if you need to do anything.

A few methods can also be called by the script itself (self.<function_name>(<param1…>)):

All of these functions are documented more detailed in their method documentations.

Script Lifecycle

The constructor will always be called first. Do your initialization here. Update will always be called before draw. The two functions are called in a loop, and will repeatedly execute. exit is always the last method call.

See the method documentations for further information.

draw(canvas: Canvas.Canvas)[source]

Called after update. Make any modifications of the canvas you want to do here. After this method has finished executing, the canvas buffer will be sent to the arduino and displayed.

Parameters:canvas – the canvas you can draw on. will be displayed on the arduino

Called when the manager gracefully wants to stop this script. This instance will be discarded of after.


Get a list of connected clients. The list will only contain the ids as given by zmq, which may be used to send data to clients. To send data to all clients, use send_object_to_all.

Returns:list of zmq ids.

Called when a client connects

Parameters:id – id of the client that disconnected

Called when a client disconnects

Parameters:id – id of the client that disconnected
on_data(data_dictionary, source_id)[source]

Called whenever the android app sends data for the script.

  • data_dictionary – a dictionary of data received from the android app.
  • source_id – the network id of the sending android device



Will restart the current script. exit() will be called on this instance. A new instance will be created. No additional arguments can be given.

send_object(obj, target)[source]

Send an object to the target id. The object can be anything, but a dict is probably easiest. No JSON serialization needs to be performed by you.

  • obj – the object to be sent
  • target – target id of the client



Send an object to all connected clients. TThe object can be anything, but a dict is probably easiest. No JSON serialization needs to be performed by you.

Parameters:obj – the object to be sent

Change the frame period with which the script will be updated

Parameters:period – the target frame period. resulting frame rate must be 0 <= f <= 60, in Hz

Change the frame rate with which the script will be updated

Parameters:frame_rate – the target frame rate. must be 0 < = f < = 60, in Hz
start_script(script_name, source_id)[source]

Will load the class in the scripts/ folder that has the given name in the file with the same name.

  • script_name – the name of _both_ the script and the class implementing the callback functions
  • source_id – the id of the client requesting the script to be loaded

Called before draw. Do any updating you want to do here.

Parameters:canvas – canvas object for information like width and height