Python Interface
If you’re looking to quickly write some Python code to control your lights, you can easily run lightbulb scripts using ls_module.py. This module performs the necessary runtime initialization and offers a clean entry point for running a script.
In the source distribution, the examples/python directory contains example
programs that show how to embed lightbulb scripts inside Python code.
Note that each script is run in its own thread. There is up to one script that is considered to be the foreground job. Whever the foreground script finishes, the system obtains the next script in the queue and launches it. This process continues until the queue is empty.
There can also be an abitrary number of background scripts. There are no queues associated with these scripts, and they all run simultaneously.
Setup
To be able to use ls_module, you first need to do at least the minimal installation, as described in Basic Installation.
Usage
Before running any scripts, the module needs to be initialzed once with configure(). After that, you can queue up an arbitrary number of scripts with queue_script(). For example:
from bardolph.controller import ls_module
ls_module.configure()
ls_module.queue_script('time 10 on all')
ls_module.queue_script('time 5 off all')
This program waits 10 seconds, turns on all the lights, and then turns them all off again after 5 seconds.
The configure() function performs internal initialization, and then discovers the lights out on the network.
There are several function calls available form ls_module, described below:
queue_script(script: str)
Call this function with a string containing the script to run. That script will be added to the end of the queue. If the queue is empty, the script will be executed immediately.
run_script(script: str)
This function stops any script that is currently running and clears the queue. It then immediately runs the script that was passed in as a string. This function is useful if you want to run a script right away.
spawn_script(script: str)
This function launches the script in the background. It has no direct impact on the other background scripts.
All of the above functions return an instance of job_control.Agent, which is in the source code under bardolph/controller/lib. Notable methods of this Agent object allow you to query whether it’s running via is_running(), or stop the script’s execution by calling request_stop().
In the following example, a script with an infinite loop turns the lights off and on every 15 seconds. It is allowed to run for 5 minutes.
import time
from bardolph.controller import ls_module
ls_module.configure()
agent = ls_module.queue_script('time 15 repeat begin on all off all end')
time.sleep(5 * 60)
agent.request_stop()
Note that the VM instance execting the script runs in a separate thread.
Example Code
The examples in embeded are documented more thoroughly and illustrate some basic use cases. To get them, you need to pull down the source code as described in Basic Installation.
hello_lights.py turns all the lights on, waits 5 seconds, and turns them off again. https://github.com/bardolph-automation-inc/bardolph/blob/master/examples/python/hello_lights.py
stop_demo.py, shows how to stop a script that contains an infinite loop. https://github.com/bardolph-automation-inc/bardolph/blob/master/examples/python/stop_demo.py
kbd_demo.py accepts input from the keyboard and sets the color of the lights accordingly. https://github.com/bardolph-automation-inc/bardolph/blob/master/examples/python/kbd_demo.py
You can try these scripts from the bardolph directory with:
python -m examples.python.hello_lights
python -m examples.python.stop_demo
python -m embedded.kbd_demo