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 embedded directory contains example programs that show how to embed lightbulb scripts inside Python code.

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 a bunch of internal initialization, and then discovers the lights out on the network. After that, it spawns a thread to repeat the discovery process every 5 minutes, continuously refreshing the internal list of available lights.

Your code can queue up jobs at any time, even while others are running. In the above example, the first call to queue_script() returns immediately, although the lights won’t come on until 10 seconds have elapsed. The second script, which turns the lights off, gets queued up asynchronously while the first script continues to run. That second script will start immediately after first one finishes.

The queue_script() function compiles the incoming string and puts the resulting VM machine code into a queue. That queue is processed by a separate thread that is spawned by the JobControl class.

You can use the return value from queue_script() to access the process that executes the script. That value is 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.

You can try these scripts from the bardolph directory with:

python -m embedded.hello_lights

python -m embedded.stop_demo

python -m embedded.kbd_demo