=====Pimoroni Rainbow Hat for the Raspberry Pi=====
{{:supported_hardware:rainbow-hat.jpg?600 |}} The Rainbow Hat has 7 individually controllable RGB led’s, a temperature and barometer sensor, 3 touch buttons, 4 button indicator LED’s and a 4 character alpha-numeric LED display. With this plugin you can control them all from XTension using this as a small interface or just a data readout. You can read more about the Rainbow hat on the [[https://shop.pimoroni.com/products/rainbow-hat-for-android-things|Pimoroni website]]
You can purchase the Hat in the US from [[https://www.adafruit.com/product/3354|Adafruit]] or from Amazon and probably many other retailers I’m not as familiar with.
The Rainbow Hat plugin for XTension requires at least [[:current|XTension version 9.4.27]]
The Rainbow hat will work with any recent raspberry pi or raspberry pi Zero though you won’t be able to connect it to XTension unless it is a pi that supports either WiFi or Ethernet networking.
----
====XTension Setup====
In the Interface List window create a new plugin instance and select “XTension Kits” as the plugin type. Save the interface and enable it. You only need one instance of this plugin running for all devices that support it so if you already have one running you do not need to create another.
Initially nothing will happen since we haven’t installed the software on the raspberry pi yet. Thats all the setup for the XTension side.
----
====Raspberry Pi Setup====
Follow the instructions for installing the Rainbow Hat pi software from the [[https://github.com/pimoroni/rainbow-hat|Rainbow Hat Github archive]].
Once you’ve done that you’ll need to install the Python program that talks to the XTension plugin. You can download that directly to your pi by executing the command:
curl -o ./xtrainbowhat.zip https://machomeautomation.com/files/py/xtrainbowhat_0.1.zip
unzip ./xtrainbowhat.zip
You can of course download that file to anywhere on your Pi that you wish but from here on I will assume that you downloaded it to your pi’s home directory and we will run it from there.
There are several options you can edit or change in the xtRainbowhat.py file there. You can open it in nano or any other editor you like and look at the first few lines:
thisDeviceName = “Lab Rainbow Hat”
Change this to give your Pi a name that describes it better than the one I gave mine. This name will be used by XTension to create names for the various units so it’s important that it be descriptive, especially if you might ever have more than one such device.
pollingInterval = 5
this is how many seconds between reading the temperature and pressure sensors. If any difference in temperature is noted the new values will be sent to XTension. Every 5 seconds might be a bit much, probably every 30 is plenty.
connectionStatusIndicator = 6
You can devote one of the rainbow LED’s to show the status of your connection to XTension. The LED’s are numbered 0 through 6 with 6 being on the left hand side so I am devoting my first LED to showing me if XTension is running and talking to it. If you wish to use all your LED’s for either a rainbow graph or other indicators then you can set this to None.
sendCPUTemp = true
If this is set to true it will create a unit in XTension for the CPU temp. This will be scanned and updated with the same pollingInterval you set above. This may be interesting, or it may be useless, up to you.
rssiInterfaceName = ‘wlan0’
If this is set to an interface name then it will send the signal strength of the WiFi to another unit in XTension. If you are not interested in this value or if your Pi is connected via Ethernet then set this to None to disable it. If scanning then this will also be updated at the same polling interval you set above. Most raspberry pi’s with WiFi should have the wifi network named “wlan0” by default. However you might also have a new “predictable” name or some other name depending on your setup. If you turned any of those things on you hopefully know the name of the network interface you created and can put it in here.
Once you’re happy with those settings you can exit the editor and save the file. If you used nano it’s control-o to output the file and control-x to quit.
----
====Run the program at bootup====
Since we want to run the program when the Pi boots we need to create a systemd startup file for it and then enable that with the system. You can create the startup information by by doing:
sudo nano /lib/systemd/system/xtinterface.service
and pasting the following code into that new file:
[Unit]
Description=XTension Interface for Rainbow Hat
After=network.target
[Service]
ExecStart=/usr/bin/python3 /home/pi/xtrainbowhat/xtRainbowhat.py
[Install]
WantedBy=network.target
If you installed the files in a different place or renamed the folder you may have to alter that path in the [Service] section.
Save that by doing a control-O and then exit the editor with a control-X.
Now we need to tell the system to enable that at startup, to set that up issue the next few commands:
sudo systemctl daemon-reload
sudo systemctl enable xtinterface.service
Now reboot your pi via:
sudo reboot
and when it reboots all the necessary units should appear in XTension!
----
====The XTension Units====
{{ :supported_hardware:rainbowhat-units.png?900 |}}
In XTension you’ll get first a “generic” unit that represents the device itself. That unit’s status will reflect the availability of the Pi on your network.
===Buttons===
Each of the three buttons will create a Unit. You can write code in the On and Off scripts to know when someone presses and releases one of the buttons.
===LEDs===
Each of the 3 LED’s above the buttons will receive a unit. Turning the unit on or off will turn on and off the LED’s on the board.
===Rainbow LEDs===
Each LED on the board will create a color and color temperature capable Unit that you can use to control the color and brightness of the led as if it were any other color capable device in XTension. There will also be a Unit called “All LEDs” that you can use to set the color of all the LED’s at once. Useful for turning them all off for instance.
----
====Using the Display====
Several scripting commands are added for sending information to the display. As of version 1,0 of the plugin no attempt is made to scroll a message or anything like that. You can send 4 characters to it via a scripting command using the name from the above “generic” unit like this:
tell xtUnit “name of the Generic unit created above” to display( “HELO”)
To clear the display use the cleardisplay command like:
tell xUnit “name of the Generic unit created above” to cleardisplay()
----
====Using the rainbow graph====
In addition to controlling the LED’s individually you can also display a colored graph using the entire array or a portion of it (reserving led’s at one end or the other for some other indicator if you wish) the commands to send data to the graph are graph1 and graph2.
the Graph1 and Graph2 commands are the same except that graph1 starts at green and turns to red when it reaches max, graph2 starts at red and reaches green at max.
Each call requires several parameters:
graph1or2( Value, max_brightness, start_pixel, end_pixel, hue_range, hue_start)
* **Value** required. Must be a floating point number between 0 and 1 so you may have to do some math on the value you wish to display first.
* **max_brightness** Optional a float between 0 and 1. 1 being the brightest. 0.1 is a usable dim value and anything lower than 0.05 does not seem to display at all. Defaults to 0.1
* **start_pixel, end_pixel** optional, integers between 0 and 6 defaulting to 0 and 6. If you wanted to keep pixel 0 for some other display then passing 1 as the start_pixel would make it not be part of this graph. Same if you wanted to reserve pixel 6 for something else, setting end_pixel to 5 would preserve it.
* **hue_range** optional defaults to 120
* **hue_start** optional defaults to 0
tell xUnit “name of generic unit above” to graph1( 0.7)