Getting Started with Automation HAT, pHAT and HAT Mini

Automation HAT is an all-singing all-dancing monitoring and automation board, with three each of 0-24V tolerant inputs, sinking outputs, relays, and ADC (analog to digital converter) channels that allow you to read voltages from 0-24V, as well as an additional 3.3V ADC channel and several GPIO pins broken out (SPI, serial, etc.)

Automation pHAT is Automation HAT's little bro', with all the same features, except that the pHAT has just one relay and no status LEDs. It's now discontinued, but fear not!

Automation HAT Mini is our updated version of Automation pHAT, it has all the same functionality but we've also managed to squeeze in a nifty little LCD screen.

Any of them are great for monitoring and controlling devices in your home, as much of the control circuitry in your home appliances will operate at 12 or 24V.

DO NOT use Automation HAT, pHAT or HAT Mini with mains voltages, or any voltages higher than 24V!

This tutorial will show you how to install the Automation HAT Python library, and then walk through its functionality, finishing with an example of how to monitor and log on/off events, such as the number of times a coffee machine is used.

For a fantastically understandable and straightforward explanation of the functionality of Automation HAT, including how relays work, then check out Tanya's blog post!

Installing the software

We always recommend using the most up-to-date version of Raspberry Pi OS (Bookworm or later), as this is what we test our boards and software against, and it often helps to start with a completely fresh install.

If you're using an existing install it's a good idea to run sudo apt update and sudo apt upgrade to make sure everything's up to date before you install our library.

The Automation HAT library will autodetect whether you're using the HAT, pHAT or HAT Mini and adapt the library as required.

Open a new terminal (Ctrl-Alt-T, or find it in the Raspberry Pi menus), and type the following, making sure to type 'y' or 'n' when prompted:

git clone https://github.com/pimoroni/automation-hat
cd automation-hat
./install.sh

The install script enables I2C and SPI and (optionally) will set up a virtual environment for you, which you will need to be able to install Python packages in recent versions of Pi OS.

Once that's done, reboot your Pi to let the changes propagate.

Running the examples

To run an example, you'll first need to switch to your virtual environment - if you let our installer set one up you can type this command in the terminal to do that:

source ~/.virtualenvs/pimoroni/bin/activate

There are several example scripts provided with the Automation HAT library. If you asked the installer to copy them to their own directory, they can be found in ~/Pimoroni/automationhat/examples/. They are sorted into a hat and a hat-mini directory - you can navigate to them using

cd ~/Pimoroni/automationhat/examples/hat/

or

cd ~/Pimoroni/automationhat/examples/hat-mini/

Let's run the output.py example, which will toggle the outputs and relay/s on and off, as well as two of the three coloured LEDs (Comms and Warn!) if you're using the HAT. Open a new terminal window or tab and type the following to run the example:

python3 output.py

Type control-c to exit the script.

Try running the other examples - analog.py, input.py, and relay.py - in the same way that you just did:

python3 analog.py
python3 input.py
python3 relay.py

Using the software

Open a new terminal and type python3 to open a new Python prompt.

Type the following to import the Automation HAT library, from which we'll call functions and create instances:

import automationhat

Analog (ADC) channels

The analog channels will return a floating point number between 0 and 24, representing the voltage measured on each channel. The three screw terminal connected channels are tolerant up to 24V, while the fourth channel, available on the broken out pins in the centre of the board, can measure up to 3.3V.

Note that the ADC channels have an approximate ±2% accuracy, and you should take this into account when looking at your readings.

To read analog channel 1, type the following:

value = automationhat.analog.one.read()
print(value)

The analog channels can be referenced either by automationhat.analog.one.read(), automationhat.analog.two.read(), etc, or by automationhat.analog[0].read(), automationhat.analog[1].read(), etc. Note that the channels are indexed from 0 to 3 in the latter case.

Try now connecting a short piece of wire between one of the 5V screw terminals and the analog channel 1 screw terminal, and read the channel again, as you did before. What value do you get back?

Inputs

The three input channels are, again, tolerant up to 24V. Their state will be low below 1V, high between 3 and 24V, and undefined (either low or high) between 1 and 3V (these are approximate, not exact values). When read, they will return 0 for low and 1 for high, and they can be read in a very similar way to the analog channels:

state = automationhat.input.one.read()
print(state)

Again, they can be referenced automationhat.input[0].read(), automationhat.input[1].read(), and so on, using indices rather than the word form of the channel numbers.

Try the same test as before with the analog channel, and connect a short length of wire from one of the 5V terminals to input channel 1. It should now be pulled high, and the LED indicator light on channel 1 should light! Try reading the state again and confirm that it has changed from 0 to 1.

Outputs

The outputs on Automation HAT are sinking, so your load should be switched on the ground side, i.e. 12/24V (from supply) -> load -> output terminal -> ground (from supply).

We'd suggest testing them with an LED, and an appropriate voltage-limiting resistor if necessary, connecting the anode or positive leg of your LED to one of the 5V terminals on Automation HAT and the cathode or negative leg to output one. To toggle the output on and off, you can either use:

import time

while True:
    automationhat.output.one.on()
    time.sleep(0.5)
    automationhat.output.one.off()
    time.sleep(0.5)

Or:

import time

while True:
    automationhat.output.one.toggle()
    time.sleep(0.5)

Or:

import time

while True:
    automationhat.output.one.write(1)
    time.sleep(0.5)
    automationhat.output.one.write(0)
    time.sleep(0.5)

The inputs, outputs, and relays also have convenient .is_on() and .is_off() methods that allow you to query whether they are currently turned on or off.

Try the following:

while True:
    if automationhat.input.one.is_on():
        print('ON')
    else:
        print 'OFF'
    time.sleep(0.5)

Now try bridging one of the 5V terminals to input one with a short length of wire or a male to male jumper wire, and watch the results.

Relays

Relays are mechanical switches that are turned on and off by an electromagnet on one side. They work in much the same way as the outputs, although they can tolerate up to 2A each and should be switched on the high side rather than the low. Plus, they have the advantage of having both normally open and normally closed sides.

Which side you choose to use - the normally open or normally closed - depends on the default state you want. If you're switching a device that will be switched off a majority of the time and then will be switched on then you'll want to use the normally open side, and if your device will be switched on a majority of the time and then switched off then you'll want to use the normally closed side.

You'll need an LED and a 470Ω resistor for this part. We're going to use the first relay to toggle the LED on and off, but you could use any device that takes up to 24V, as long as you remember to connect it on the high side, i.e. 12/24V (from supply) -> relay -> load -> ground (from supply).

We'll use a mini breadboard to connect everything up with a few jumper wires.

First, pop your LED into the breadboard, taking note of which leg is which; the longer leg is the positive side. Place your 470Ω resistor on the positive side of the LED; the direction doesn't matter for the resistor.

Now, take a male to male jumper wire and connect it to the resistor in the breadboard and screw the other end into the COM terminal on relay 1. Use another male to male jumper wire to connect the NO terminal on relay 1 to one of the 5V terminals.

Finally, connect another male to male jumper wire to the other leg of your LED (the shorter one) to one of the GND terminals. It should look something like the image below once connected up.

We'll use a little while loop to toggle our LED on and off. Type the following:

while True:
    automationhat.relay.one.toggle()
    time.sleep(0.5)

Your LED should now be blinking on and off, once every second.

The relays work, in terms of their methods, just the same as the outputs. As well as the .toggle() method that toggles the state of the relays, there are .on() and .off() methods that do exactly what they say, and .is_on() and .is_off() methods that return Boolean (True or False) values depending on whether the relays are on or off.

Like the outputs, there's also a .write() method that accepts a Boolean value (0 / 'False', or '1' / 'True') to switch them off or on respectively.

Try connecting one LED to the normally open side, and one to the normally closed side of the same relay to see how their behaviour differs.

Uses for Automation HAT, pHAT and HAT Mini

Just to reiterate... be EXTREMELY careful when dismantling electronic devices, and ensure that the circuitry that you're tapping into is 24V or less and is unplugged and/or switched off when you're working with it!

The control circuitry of many home devices like coffee machines, low voltage lighting systems, some boiler and air conditioning thermostats, garage doors, and more, operate on 12V or 24V and could be controlled or monitored with Automation HAT.

Often, a good place to tap into is a push button that operates, for instance, a coffee machine. Measuring the current and voltage across the button when pressed (put your multimeter in series with the button) will give you an idea of whether it falls within the 24V range of Automation HAT's outputs and relays, and the combined 500mA limit of the outputs and 2A per relay limit.

As well as controlling devices, you could also use Automation HAT's inputs to monitor a device. Why not connect an input on Automation HAT in series with your coffee machine's button or beeper that signals when the coffee is ready, and then post a message to your office's Slack channel?

That's all folks!

Search above to find more great tutorials and guides.