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 flashlight.py
, and the class name would be flashlight
.
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:
update()
, where the state may be updateddraw()
, where the matrix content may be drawnon_data()
, called when messages from clients arriveexit()
, last call before the instance is discardedon_client_connected()
, called with an id parameter when a new client is approvedon_client_disconnected()
, called with an id parameter when a client has disconnected
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...>)):
send_object()
to send objects to specific clientssend_object_to_all()
to send objects to all clientsstart_script()
start a script by name. will replace current script.restart_self()
restarts the current scriptget_connected_clients()
gets a list of approved client idsset_frame_period()
allows to set a custom update cycle period in secondsset_frame_rate()
allows to set a custom update cycle calling rate in Hz
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 Returns: nothing
-
exit
()[source]¶ Called when the manager gracefully wants to stop this script. This instance will be discarded of after.
-
get_connected_clients
()[source]¶ 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.
-
on_client_connected
(id)[source]¶ Called when a client connects
Parameters: id – id of the client that disconnected Returns:
-
on_client_disconnected
(id)[source]¶ Called when a client disconnects
Parameters: id – id of the client that disconnected Returns:
-
on_data
(data_dictionary, source_id)[source]¶ Called whenever the android app sends data for the script.
Parameters: - data_dictionary – a dictionary of data received from the android app.
- source_id – the network id of the sending android device
Returns: nothing
-
restart_self
()[source]¶ Will restart the current script. exit() will be called on this instance. A new instance will be created. No additional arguments can be given.
Returns: nothing
-
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.
Parameters: - obj – the object to be sent
- target – target id of the client
Returns: nothing
-
send_object_to_all
(obj)[source]¶ 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 Returns: nothing
-
set_frame_period
(period)[source]¶ 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 Returns: nothing
-
set_frame_rate
(frame_rate)[source]¶ 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 Returns: nothing
-
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.
Parameters: - 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