http://www.bardolph.org

Basic Installation

This page contains instructions for setting up only the interpreter and other command-line tools. This is a much simpler installation than setting up the web server, which is described in Web Server Installation.

Because the Bardolph wheel designates lifxlan as a dependency, it may also be downloaded and installed.

In order to do the installation on a Raspberry Pi, you should probably first create a Python virtual environment. This is necessary because that version of Linux is what’s known as an “externally managed environment”. For example:

python -m venv bardolph-venv
source bardolph-venv/bin/activate

After the activation, your shell prompt will change and have “(bardolph-venv)” automatically prepended to it. Note that you will need to activate the virtual environment with source bardolph-venv/bin/activate every time you log in. Note that “bardolph-venv” is just a suggestion; you may name the the virtual environment any way you see fit.

For more information about virtual envronments, please see the official Python documentation. They are a complex subject, and an extensive discussion of them is outside the scope of this document.

With the virtual environment activated, you can install the Bardolph package:

pip install bardolph

After this intallation, the lsc, lsrun, and lscap commands will be available whenever your virtual environment is activated. In addition, if you’re planning on embedding scripts in your own Python program, the Bardolph support code will be importable.

To get a copy of the sample script files, you should get the full source tree with:

git clone https://github.com/al-fontes-jr/bardolph

Testing the Installation

To do a quick sanity check:

lsrun -h

This should display a help screen. To verify access to your actual lights:

lscap

This will discover the lights on the network and output a plain-text report with the state of each light it finds. If you don’t have any lights, but still want to test the installaton, use fakes, which are software simulations of real lights:

lscap -f

As another quick test, you can try turning all the lights off and on again from the command line:

lsrun -s "off all"
lsrun -s "on all"

The source distribution includes some examples in a directory named scripts. For example:

lsrun scripts/on-all.ls

The -f flag works here as well, which allows you to try out scripts without accessing any actual lights.

Note that the above commands are documented in Command-Line Tools.

Upgrading to Latest Version

From time to time, the package will be updated with fixes and new features. To upgrade to the latest verstion:

source bardolph-venv/bin/activate
pip install -U bardolph

Alternative: Build and Install

You can use this process if you want to build from source and install the local package. In this case, you should still use pip as your package manager, so that you can use it later to remove your build and clean out unwanted files.

To do this, you need to have setuptools installed.

With setuptools on your system:

pip install lifxlan setuptools build
git clone https://github.com/al-fontes-jr/bardolph
cd bardolph
python -m build
pip install --no-index --find-links ./dist bardolph

Note that the invocation python -m build creates the dist directory. Within that directory, it creates a .whl file containing the new package. When you run pip, it finds that file and installs it. You need to install lifxlan manually because the installation of bardolph is limited to local files.

Although it isn’t necessary, you may want to try running the Python unit tests to validate your copy of the source code and Python environment:

python -m tests.every_test

When you get a newer release of the code, you can upgrade it with:

python -m build
pip install --upgrade --no-index --find-links ./dist bardolph

Uninstalling

Uninstall with:

pip uninstall bardolph

This will work whether you installed a downloaded package, or built and installed a package locally. If you are using a virtual environment, you need to activate it before runnning the uninstall command.

Installing lifxlan Library

If you are successfully acccessing all of your devices, you can skip this section. However if you have a Tube device which is not being discovered, the following information may be helpful.

All access by Bardolph to the LIFX devices is handled through the lifxlan library. The source code for that library is on Github, at https://github.com/mclarkk/lifxlan. A packaged version of the library is available on PyPi at https://pypi.org/project/lifxlan/. If you install Bardolph using pip, it will automatically install the lifxlan package from PyPi as well.

However, that library contains an internal list of known products, which can be out of date. Whenever LIFX releases a new product, there is a lag before the lifxlan library is updated with that product’s specifications. This means that a fairly new type of device may not be discovered.

For example, as of the time of this writing (March, 2025), the version of lifxlan on PyPi does not recognize Tube devices, such as the Tube E26. If a script attempts to access such a device under these conditions, there will be an error message about a light not being found, and the script will not work.

In this situation you can probably fix the problem by downloading the latest source code for lifxlan and installing the library from that code.

To do so, first activate your virtual environment. For example:

source bardolph-venv/bin/activate

Then, with the virtual environment active, run the following command to remove the PyPi version of the package:

pip uninstall lifxlan

Finally, with the virtual environment still active, run the following commands from your home directory to install from the latest source code:

git clone https://github.com/mclarkk/lifxlan
cd lifxlan
python setup.py install

When this is complete, you should be able to see devices that were previously undiscovered.

Note that there may still be devices that are missing. The definitive list is available at https://github.com/LIFX/products/blob/master/products.json. If your device is on that list, but still not handled by lifxlan, you may want to try running generate_products_file.py, although I haven’t tried it and don’t recommend it.