Before you install the software for this project make sure your Raspberry Pi is running the latest Raspbian Jessie or Jessie Lite operating system. If you're new to using the Raspberry Pi be sure to read the first few Learn Raspberry Pi guides to learn how to burn an operating system to SD card, connect the Pi to your network, and access the Pi's command terminal with SSH.
Also make sure your Raspberry Pi is connected to the internet with a wired or wireless network connection so software dependencies can be installed before continuing.
Installation
To install the dashboard software from its home on Github connect to your Pi's command terminal and run the following commands:
sudo apt-get update sudo apt-get install -y git build-essential curl python-pip python-smbus python-dev git clone https://github.com/adafruit/Pi_Physical_Dashboard.git cd Pi_Physical_Dashboard sudo pip install -r requirements.txt
After running the last command you should see pip print that it successfully installed dependencies and is cleaning up:
The software will be installed in the /home/pi/Pi_Physical_Dashboard folder and can be run with its main.py Python script. However before running the dashboard software you'll first need to configure it by following the next section.
Configuration
To configure the dashboard software you need to edit its config.ini file in a text editor. For example you can use the nano text editor on the Pi by running this command in the Pi_Physical_Dashboard folder:
nano config.ini
Inside the file you'll see comments (lines that begin with #) that describe the configuration.
At a high level the configuration file defines a list of widgets which are items on the dashboard that can be manipulated. For example a seven segment LED display or automotive stepper gauge is a widget that be added to a dashboard. The software for this project will run a little REST API server that allows any program to control the value displayed by a widget on the dashboard.
Widgets are defined by sections in the config.ini file. A section starts with the name of the widget in square brackets. On the following lines are configuration options for the widget. In particular every widget must have a type option that defines the type of widget, like SevenSegmentWidget for a seven segment display. Depending on the type of widget there might be other options provided.
For example the configuration shows a commented out seven segment widget:
# Example of a seven segment display called 'cpu'. The type is SeveSegmentWidget, # the I2C address of the device is specified as 0x74, and the number of digits # to show after the decimal point is set to 0. #[cpu] #type = SevenSegmentWidget #address = 0x74 #decimal_digits = 0
If the comments are removed then the widget would be enabled:
# Example of a seven segment display called 'cpu'. The type is SeveSegmentWidget, # the I2C address of the device is specified as 0x74, and the number of digits # to show after the decimal point is set to 0. [cpu] type = SevenSegmentWidget address = 0x74 decimal_digits = 0
Notice this widget has the name cpu (the value inside the square brackets), has a type of SevenSegmentWidget (i.e. is a seven segment LED display), and sets a few seven segment display specific options like the I2C address to 0x74 and the number of digits to display after to decimal point to zero.
Scroll through the rest of the configuration file and you can see examples of all the possible widget types and their options:
- SevenSegmentWidget - seven segment LED display
- AlphaNum4Widget - quad alphanumeric LED display
- BicolorBargraph24Widget - bicolor 24 segment LED bar graph display
- AutoGaugeWidget - automotive stepper motor gauge
Add to the config.ini your own widget configuration. For example if you wanted to define a seven segment display called foo (with I2C address 0x72) and an automotive gauge called bar (on motor HAT port M1) your config would look like:
[foo] type = SevenSegmentWidget address = 0x72 [bar] type = AutoGaugeWidget motor_id = 1
Save the configuration file and exit nano by pressing Ctrl-o, enter and then Ctrl-x.
Usage
Once the dashboard configuration has been set you're ready to run the program. In the Pi_Physical_Dashboard folder execute the following command to start the server:
sudo python main.py
NOTE: When you start the dashboard server it will move all automotive gauges as far left as possible to put them in an initial 'home' position. You might see the gauge vibrate as it hits the stops which prevent it from moving completely around. This is OK and not something that will damage the gauge. Once the gauge stops moving you should remove the dial from the shaft and place it back on so it's pointing in the 0 position you want for your dashboard.
If the dashboard starts successfully you should see a line printed with the name of each configured widget, similar to the following:
If the dashboard fails to start check the output to see if it gives a hint as to what widget might be failing. In particular make sure the I2C address of each widget is set correctly. Use the i2cdetect tool to check the Pi can see the widget at the address you expect.
To check the server is working you can access its widget list from your web browser. Open a browser and connect to http://raspberrypi:5000/widgets (if you renamed your pi change raspberrypi to the name of your pi, or if that fails check your router to see what IP address is assigned to the Pi and use that IP in the URL). You should see a JSON formatted list of widgets, for example:
This widget list endpoint is useful for checking that all the configured widgets are available.
Now to set the value of a widget you can make an HTTP POST request against the http://raspberrypi:5000/widgets/widget_name endpoint, where widget_name is the name assigned to a the widget. As either a query parameter or form parameter in the body of the request, add a parameter called value which is set to the value you'd like to display on the widget.
An easy way to make this request is with the curl command. You can install curl on your computer (if using Windows you might need to install cygwin to get curl) or you can even run curl from the Raspberry Pi running the dashboard.
For example to set the value of the widget named cpu to 55 you would run the following curl command:
curl -d value=55 http://raspberrypi:5000/widgets/cpu
Try using curl to set a value for a widget you have defined on your dashboard. You should see the widget update with the new value! If you don't see the widget update make sure you are using the right name for the widget. Also check the output of the main.py process to see if it prints a more useful error message to help you debug the issue.
One important thing to note is that each widget has a range of values they can have set:
- SevenSegmentWidget - Set any floating point numeric value in the range of -999 to 9999. Depending on the decimal digit precision the value might be rounded to fit on the display. If the value won't fit then ---- is displayed. You can also send the value colon_on to turn on the colon, and colon_off to turn off the colon.
- AlphaNum4Widget - Set any floating point numeric value just like the seven segment widget, or set any 4 character alphanumeric string. Long strings will be truncated to their first 4 characters.
- BicolorBargraph24Widget - Set any floating point percentage value in the range of 0 to 100 (don't include a % sign). This will illuminate the specified percent of LEDs green. You can also send a value in the range 200-300 to set that percent of LEDs yellow, or 400-500 to set that percent of LEDs red.
- AutoGaugeWidget - Set any floating point percentage value in the range of 0 to 100 (don't include a % sign). This will move the gauge's needle to the specified percent value within its range of movement. I.e. a value of 50 will move to the middle of its 315 degree movement arc.
Some more examples of setting values with curl look like:
# Set an alphanumeric widget called foo to have a value COOL: curl -d value=COOL http://raspberrypi:5000/widgets/foo # Set a bicolor bargraph widget called bar to be 35% illuminated: curl -d value=35 http://raspberrypi:5000/widgets/bar # Set a bicolor bargraph widget called bar to be 75% illuminated red: curl -d value=475 http://raspberrypi:5000/widgets/bar # Set an auto gauge widget called gauge to be at 35%: curl -d value=35 http://raspberrypi:5000/widgets/gauge
NOTE: If your auto gauge widget moves the wrong way you can invert its movement with the invert option for the widget. See the comments in the config.ini file for details.
That's all there is to updating data on the dashboard! You can use any programming language which can make HTTP requests (which is pretty much every language!) to control a dashboard. For example with Python you can use the requests library to make HTTP POST requests against a dashboard. See the demo.py code included in the source for the project to see an example of Python controlling a dashboard with random values.
If you'd like to make the dashboard start every time the Pi boots, see this excellent guide on using systemd to create a service that runs the dashboard's main.py script. The latest Raspbian Jessie operating system uses systemd just like the BeagleBone Black mentioned in the guide.
Woo hoo, you now have a cool physical dashboard you can control with web requests! Hook up the dashboard to display interesting metrics like load from a server, the status of sensors in your home, and much more.
