Kinetic Courier

The Kinetic Courier is an alert system for your IoT things. When something happens, it can ring a bell, wave a flag or light some NeoPixels. You can even connect it up to Alexa and IFTTT.

Who is this for?

So... Can't I get alerts by just sending notifications to my phone? Yes, yes you can.

This project is for someone who wants a fun alert system, different from phone notifications. It definitely gets your attention!

Cost About $60 USD, not including 3D print materials.

SkillLevel:Advanced.

This project requires skills in soldering, 3D printing and assembly, and python coding.

Time: About 4 hours for software setup and assembly. 3D printing - Base: 7hr 45min; Top: 4hr 45min. Both components require supports. This was on a small and slow MonoPrice Mini Select 3D Printer. If you have a Prusa MK3S, you could shave hours off the print time.

Overview

The Kinetic Courier (KC) is designed to be a general purpose physical alert platform, so it can be modified for different situations. You can place it anywhere - your living room, your office - and be reminded that something needs attention, without being tied to a phone or computer.

The KC needs a triggering gadget (or IFTTT) to work. I've used an Amazon Echo (with Alexa) or an Adafruit Huzzah/ESP8266 as the trigger/sender in supplied examples. The KC is the receiving point. The Adafruit_IO API running with adafruit.io is the glue, the connection between the sender and the Kinetic Courier.

Here are some sample use cases, using IFTTT/Alexa:

• Weather condition alert - Hot/Cold/Rain/Snow (example code supplied)
• Recurring reminders, like when to take medications (IFTTT example supplied)
• Dinner Bell for the kids, or Sick Room Call (IFTTT example supplied)
• ISS (International Space Station) is over my location (example code supplied)

Additional IOT hardware required:

• Garage Door is open (magnetic switch), use Option 1 in link; example code supplied
• Laundry is done (vibration detector)
• Sump pump started (vibration detector)
• Customer entered when you're in the back room (PIR motion detector)
• Remote equipment light turned on or off (photocell)

You get the idea - it's pretty adaptable.

Adafruit.io is required for all alert examples. A python program running on a raspberry pi W will check for new data on adafruit.io and act accordingly.

There are sample behaviors and animations for:

• NeoPixels
• A Desk Bell rung by a solenoid
• Moving a flag with a servo

Two different voltages are used. The easiest way to get both was to use a Buck-Boost converter:

• 12V to activate the solenoid
• 5V for the servo and NeoPixels

I used the Verter Buck-Boost converter from Adafruit.

Process

Build

BasicSoftwarePackages

• Download Debian Buster Lite
• Install to micro sd card. This is a good set of instructions.
• Two files need to be added to the /boot directory on the new sd image card.

On Windows, create an empty file called ssh and a file named wpa_supplicant.conf with the contents shown (second box) below

For Linux/Mac:

sudo touch ssh 
sudo nano wpa_supplicant.conf

And for Windows/Linux/Mac, enter and save the following, changing ssid and psk to your router's ssid and password:

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1 
country=US 
network={ 
ssid="Your network SSID" 
psk="Your WPA/WPA2 security key" 
key_mgmt=WPA-PSK 
}

After getting Raspbian configured, run headless (no monitor/keyboard/mouse) - insert the SD card into your pi and power up. Allow a couple of minutes for the pi to fully start up. If you are running Windows, download the putty terminal emulator to connect to the pi with SSH. You should be able to find the IP address from your router's web page. And, to SSH in from a Mac/Linux terminal:

ssh "192.168.0.xxx" -l pi

Where "192.168.0.xxx" = your pi's IP address (without quotes). The default password is raspberry. Be sure to change it on first login. You should also configure other settings via:

sudo raspi-config

• Network Options/Hostname (I named my host KineticCourier)
• Localisation Options
• Advanced Options - Expand Filesystem

After completing the config, reboot. When you sign back in, update packages and set up git:

sudo apt-get update
sudo apt-get upgrade # This step takes a long time! 
sudo apt-get install git-core
cd ~/pi
git clone http://github.com/thisoldgeek/KineticCourier

Cloning this github repository will create a new directory under /home/pi/KineticCourier. This KineticCourier directory contains all the assets needed for this project.

You'll also need some libraries for the solenoid, the servo and NeoPixels.

The following code sets up the pip3 installer tool, which will be used to get other libraries:

sudo apt-get install python3-pip
sudo pip3 install adafruit-io 
#see README at https://github.com/adafruit/Adafruit_IO_Python

• See the intro at: Adafruit IO Overview

Next, install the libraries for the NeoPixels, solenoid and servo:

sudo pip3 install rpi_ws281x adafruit-circuitpython-neopixel

sudo apt-get install pigpio # for servo
pigpiod -v # Displays pigpio version (1.64-1 shows as '64')
# Also install python modules for servo
sudo apt-get install python-pigpio python3-pigpio

# to run pigpio automatically at boot:
sudo systemctl enable pigpiod
  
# Solenoid modules (should be installed by default)

reference: https://learn.adafruit.com/neopixels-on-raspberry-pi/python-usage

The install of rpi_ws281x /adafruit-circuitpython-neopixel includes the library RPi.GPIO, which is used for the solenoid. The library for pigpio requires that a service is enabled/started before you can run programs against it.

If you want to use the optional shutdown button (explained here):

sudo nano /boot/config.txt
# add the following 
# pins 0-8 are default pullup on boot, work without any additional changes
dtoverlay=gpio-shutdown,gpio_pin=4

Hardware

Prepare the hardware in stages, testing as you go. This is easier to debug.

Solenoid

Step 1

To start, prepare the perma proto bonnet, the pi zero (if using the non WH version), the Verter (just the terminal block at this time) and the in-line switch.

Solder:

• Tall-pin female headers to Adafruit perma proto bonnet. The pins are soldered on the side of the board with the numbers. Trim all pins except for physical pin 4(+5V) and 6(GND)
• +V/GND wires (at least 25mm each) to corresponding bonnet pins; strip unsoldered ends
• Male headers to raspberry pi zero W, long pins up to attach the perma-proto bonnet. (Skip this step for pi zero WH, which has the headers already soldered on)
• Verter terminal block for V/GND power supply input, holes to +/- on the board
• Strip male end from in-line on/off switch and tin wires; attach +V/GND to corresponding terminal block inputs

The Verter will have 12V input (VIN pin) from a power supply attached to the in-line switch on its terminal block, and output 5V from the other (USB connector) end. The wires attached to pin 4/+V and 6/GND will connect to the corresponding +/- USB holes on the Verter - wrap them tightly temporarily to test. Trim the pins on the bonnet after soldering.

To test: Insert the in-line switch wires and power up with a 12V power supply. With a multi-meter, check that you are getting +5V (mine was 5.24V) on the 5V rail and 12V (mine = 12.24V) from the Verter VIN pin.

Step2

Prepare connections for the Verter to the solenoid. This requires soldering wires on both sides of the Bonnet board, before you solder the Verter in place.

Note: I'll refer to the vias/holes you solder wires to as pth (plated through hole)

Here's the schematic and TIP120 Pinout:

Solder the following as shown in "Solenoid Top Bonnet" photo (below):

• On the top side of the bonnet, solder a (red) jumper wire, 3 pth's below pin #13.
• The other end of the 12V VIN jumper wire, second pth from bottom of the board. This is in the same column as pin #23.
• A TIP120 transistor next to the 12V Vin, heat sink toward bottom of board. Pin "B" of the TIP120 will be in same column as pin #22.
• A 1K Ohm resistor between Pin 22 and TIP120 Base (B in photo)
• A 1N4001 diode, band side wire to bottom pth under 12V VIN. The other end of the diode is soldered to the TIP120 Collector (C in photo)
• TIP120 Emitter (E in photo) to the GND rail with a short jumper wire
• For the solenoid wires, a 2-pin Terminal Block to bottom row of Bonnet, last two pins on the left. Note +V and GND in photo.

Solder the following jumper wires as shown in "Solenoid Bottom Bonnet" photo (above):

• First: Solenoid "-" (negative/GND) to TIP120 Collector (C). This will be under the positive jumper
• Solenoid "+" (positive/V) to Verter 12V

Verter

Solder:

• Male header pins to the Verter, long side down
• +V/GND (physical pins 4 & 6 with jumper wires previously soldered on) to +V/GND pins at the USB end of the Verter. I also added a bit of hot glue to protect the plus & minus soldered pins on the pi.
• Verter to the bonnet, with VIN pin in pth between jumper wire and #13 (see "Solenoid Top Bonnet Wiring" photo above). NOTin pin #13, but the hole below it!

RemainingConnections

Next, solder three pin male headers to the bonnet on the GND rail, the 5V rail and a jumpered GPIO pin. See the photo "Solder Male Headers to Bonnet", above. The NeoPixels and servo each use a GPIO pin, 5V and GND connection. The push buttons only use a GPIO and GND, but I still used 3 male header pins to make it easier to solder. The NeoPixels, servo and push buttons will connect to these male headers with female box-headed jumper wire. See NeoPixels photo above for an example of female box-headed jumpers.

Note: Pin 18 (Hardware PWM0) must be used for NeoPixels. See yellow jumper in photo above.

NeoPixels

Two NeoPixel sticks from Adafruit are used.

With NeoPixels pointed out/away from each other (see NeoPixel Wiring photo above),

Solder:

• 110mm wire to connect 5v-to-5v; GND-to-GND; DOUT from "Board A" to DIN on "Board B"
• On "Board A" : Female box-header jumpers, 50mm long, stripped on one end, to 5V/GND/DIN, with 1N4001 diode in-line on 5V wire, diode band toward NeoPixel5V.

Push-Buttons

Two push-buttons are used; 1) shutdown the pi; 2) reset the alerts.

For each push-button (see Push-Button Wiring photo above):

• Strip two different color female box-header jumpers, 75mm long, on one end, one for each push-button. Also strip two female jumpers (same length) for GND connection, typically black.
• Solder stripped ends of black and colored jumpers to two different pins on each push-button.

Test

This would be a good time to test and debug the components. There are test python scripts in the git for checking the solenoid, servo and NeoPixels.

• Attach the box-headed wires, solenoid wires and power connections at their headers/terminals, as shown in earlier photos "Solder Top Bonnet Wiring" and "Solder Male Headers to Bonnet".

PrinttheCase

The 3D STL files can be found on thingiverse. The NeoPixels show best with a white printed case.

Assembly

Base

• First: Mount wired NeoPixels on posts. I screwed them in, because I often reuse parts. Screwing them into the posts is fiddly. Mounting with hot glue is quick and easy.
• Hot glue the push-buttons into the holes next to the power cable.
• Mount the servo in the square hole at the front of the base. Friction-fit for the servo seems to work fine, but for ultimate stability, hot glue the servo in place. Coil the wires underneath the servo, being careful not to block the pi mounting holes.
• Mount the bonnet on the pi zero with M2.5 10mm standoffs. We'll mount the pi zero to the top, through the base, in the Final Assembly. Leave nuts off until then.
• Screw the solenoid into the holes on the arched tower plate with 2 M2.5 6mm screws and nuts. Place the desk bell in the top, temporarily, and adjust the solenoid and screws so the piston is centered on the bell ringer.
• Thread the wires through the hole in the solenoid mounting plate, then through the hole at the bottom of the tower.

FinalAssembly

• Lay the top and bottom on their sides and thread the solenoid wires through the base.
• Make sure the micro sd card is inserted into the raspberry pi.
• Carefully/gently move the box-headed wires out of the way while you lower the pi/bonnet onto its mounting posts.
• Makesure none of the box headers are under the pi.
• Use 4 M2.5 14mm machine screws, through both the top and base, to attach the pi through the bonnet standoffs. Thread on the standoff nuts.
• Attach the box-headed wires, solenoid wires and power connections at their headers/terminals, as shown in earlier photos "Solder Top Bonnet Wiring" and "Solder Male Headers to Bonnet".
• Mount the "Flag Servo Horn" from Adafruit's GMailbox on the servo
• Position the Desk Bell under the solenoid piston

The solenoid has quite a kick! This causes the bell, and the whole assembly, to "walk" slightly. To minimize movement, place a small bit of blue tak under the bell and place the whole assembly on a rubber mat - the kind of tool used for opening stuck jar lids.

Software for Alerts

Adafruit IO

The KC uses the Adafruit_IO API and adafruit.io to record and send alerts to the KC. To get set up, go to Getting Started with Adafruit.io and complete the installation guide. These required software packages were already installed in the BasicSoftwarePackages section above:

pip3 install adafruit-io #for send/receive with adafruit.io
git clone https://github.com/adafruit/io-client-python.git

NOTE:Create feeds for IFTTT in a "Kinetic Courier" group. If you decide to use the Garage Door Monitor discussed below as an alert, create the feed in the Default group.

IFTTT

For some alerts, the KC uses IFTTT. Sign up at IFTTT/join. The general pattern for IFTTT feeds to adafruit.io is:

• Create a feed on adafruit.io
• Find an IFTTT service you want to use as the "IF condition"
• Decide on a trigger condition
• For the "THAT condition" (desired action), choose Adafruit
• Send data to the adafruit.io feed

Examples:

Weather

• On adafruit.io, create a feed called "weather" under the Kinetic Courier group
• Sign-in to IFTTT
• Click "Profile"/ Click "Create"/Click "this" Plus sign
• Choose a service/Search weather/Click Weather Underground
• Choose Trigger: "Tomorrow's Forecast Calls For"
• Choose condition (eg. Rain) from pull-down and type your address in map text; click "Create Trigger"
• Click "Then"/Choose Action Service: Adafruit/Send data to Adafruit.io
• Complete Action Fields for Feed Name (Weather) and Data to Save (rain)
• Review and click "Finish"

You could substitute "Snow/Cloudy/Clear" for Rain in the above example to alert for those conditions. If you want more than one condition to go to the weather feed, create another IFTTT recipe for each condition.

To check for Hot/Cold conditions, use the process above with the following changes:

• Under Weather Underground, change to check for "Tomorrow's low drops below" or "Tomorrow's high rises above" and a number in degrees F/C
• Pass the string "cold" or "hot" to the adafruit.io weather feed. Create another feed for "temps" to keep hot/cold separate from rain/snow.

Medicationand other Reminders:

DinnerBell (or Sick Room call)

You use this by saying, "Alexa trigger 'dinner is ready'". The exact phrase you are going to use needs to be stored in Step 2, "Complete the trigger fields".

ISS (International Space Station) Overhead:

GarageDoor isOpen

This example uses the Garage Door Monitor. Follow the instructions at that link through Option 1 and create the feed in the Default group. The Garage Door Monitor uses IFTTT as an option to send phone notifications, but it's not required for the KC.

After you run the test programs and you're satisfied everything is working, you can install a systemd service that will startup at boot time. The text for this service is in: /home/pi/KineticCourier/KineticCourier_service.txt.

# To install, do the following:
# cd ~/KineticCourier
#sudo cp KineticCourier_service.txt /lib/systemd/system/KineticCourier.service
# sudo chmod 644 /lib/systemd/system/KineticCourier.service
# sudo systemctl daemon-reload
# sudo systemctl enable KineticCourier
# sudo reboot
[Unit]
Description=Kinetic Courier
After=multi-user.target
[Service]
Type=idle
User=root
ExecStart=/usr/bin/python3 /home/pi/KineticCourier/kinetic_courier.py
Restart=always
RestartSec=15
[Install]
WantedBy=multi-user.target

How This Works

You can use behaviors in different combinations to uniquely signal a particular alert. Check the code - there are sample routines for solenoid, servo and NeoPixel behaviors. You'll find default alerts in the get_feeds function. Alert behaviors can be one-time, when a new value is received - or, with NeoPixels, they can continue until reset.

There is a start-up routine that lets you know the KC is up and running.

There is also a "quiet time" function in the code, with defaults for quiet (no alert functions) between 21:00 and 09:00.

Example behavior, for garage door OPEN:

• Light all NeoPixels green
• Ring the bell 3 times
• Raise the flag to 90 degrees
• Turn NeoPixels OFF
• Fade ("Breathe" function) NeoPixels about every 10 seconds until the reset button is pressed or 'SHUT" received

There is also a "safe shutdown" button for the raspberry pi, to avoid micro sd card corruption. You still need to power off.