Howto: XRP + Raspberry Pi — ILP enabled (streaming payments) power switch

— published at the XRP Community Blog

For just ~$30 in parts (Raspberry Pi, 3.3V Relay board and a few wires) you can build your own power switch that will switch on if a streaming ILP payment comes in. Payment stream stops? Power turns off.

Is this useful? Well, right now… Not really, right? There’s no easy way for people to start streaming XRP to you over ILP, but… That may change ;)

I hope I can guide you through the process of installing your Raspberry Pi and wiring your Pi to your power socket.

WARNING: YOU ARE GOING TO WORK WITH HIGH VOLTAGE ELECTRICITY! IF YOU DON’T KNOW WHAT YOU ARE DOING (or at least: the electricity / wiring part) PLEASE DO NOT SWITCH 110V/220V, BUT SWITCH A SIMPLE LOW VOLTAGE LED INSTEAD.

Depending on your experience with hard- and software it may take you between 30 minutes and a few hours to complete this howto.

1. Prerequisites

This is your shopping list:

• Raspberry Pi, model 2B or 3
• High speed Micro SD card, 4GB or more
• Decent power supply for a Raspberry Pi (the Pi is pretty sensitive)
• Either: a soldering iron and some low voltage wires, or (even better) jumper wires
• A 3.3V relay board (5V may work as well)

You’ll also need a family seed (a.k.a. “secret”), the secret for your own XRP account (wallet) starting with a lowercase s, eg. snq1b...Qoa...fo2HjPHppq3rZUG.
PLEASE NEVER SHARE YOUR SECRET WITH ANYONE!

You need to connect your Raspberry Pi to a monitor / TV with a HDMI cable, and into your switch/router with a CAT5 / CAT6 network cable. You also need to connect (USB) a keyboard for the initial setup.

If you are on Windows, you’ll also need a SSH client to connect to the Raspberry after the initial installation. Please install Putty. If you are on Mac OSX or Linux, you are already fine.

2. Raspberry Pi operating system

The Raspberry Pi needs an operating system. We’ll use the lightweight version of Debian linux: “Raspbian Stretch Lite”. Please visit:
https://www.raspberrypi.org/downloads/raspbian/

… and download the Raspbian Stretch Lite ZIP:

3. Write the OS to the SD card

To write the ZIP with “Raspbian Stretch Lite” to your Micro SD card, please download etcher. It’s an awesome and user friendly tool to write the Raspberry Pi operating system to the Micro SD card.

Insert your Micro SD card into your card reader, Launch Etcher, select the downloaded ZIP (don’t extract the ZIP) and select your SD card.

When Etcher tells you it’s done, safely unmount the SD and insert it into your Raspberry Pi.

4. Connect your Pi

Now connect your Pi. Connect your monitor, network and keyboard.

Lastly: plugin your power supply.

Your Raspberry Pi will now boot. We can move on to step #5 when your Raspberry Pi asks you to login.

To login to a freshly installed Raspberry Pi, your username is pi and your password is raspberry.

5. Basic installation

First, lets check the IP address on your local network your router assigned to your Raspberry. This is the IP you can connect to, using SSH, in a few minutes;

Enter this command:

ifconfig

Your Pi will show your IP; check the IP (inet) for eth0, the wired network interface:

The IP probably starts with 10., 172. or 192. (local network ranges). If the IP starts with 169. there is probably something wrong with your network connection.

You probably want to continue the installation from behind your own computer, allowing you to copy-paste the commands I’m going to share with you. To do this, we’re going to enable SSH on the Raspberry, allowing remote logins to the Raspberry Pi terminal.

Please enter this command:

sudo touch /boot/ssh

… and press enter. You’ll probably have to enter your password, raspberry, again.

This command creates a file (/boot/ssh) that tells the Raspberry to allow SSH connections.

Now let’s apply and reboot; enter sudo reboot and press enter.

Wait for your Raspberry to reboot and return to the login screen.

6. Login to the Raspberry Pi using SSH

Now return to your own computer.

Your computer needs to be connected to the same network the Raspberry Pi is connected to. Your computer may be connected wireless while your Raspberry Pi is connected with a wire, as long as it’s the same network.

Please open your terminal (OSX, Linux) or Putty (Windows) and create a new SSH connection to the Raspberry, using the IP you checked in step #5.

OSX / Linux users can enter this terminal command:

ssh -p 22 pi@0.0.0.0

… Where you have to replace the fake 0.0.0.0 IP with the IP of the Raspberry.

Windows users can enter the IP in the Host Name (or IP address) field, and 22 in the port field. Select SSH as connection type.

Now connect. If you are asked for a username, enter pi. You will be asked for the password, that's raspberry.

After being connected, a welcome message from the Raspberry Pi will show, asking you to change your password (now: raspberry). Enter the command:

passwd

… to change the password. Enter the existing password (raspberry) and enter a new one. Then retype your new password.

The next time you will login to your Raspberry (either with your connected USB keyboard, or using SSH) you’ll need to use your new password.

7. Update the Raspberry

You’ll want to make sure you are running the most recent (software) packages on the Raspberry. Let’s update and upgrade it;

sudo apt -y update && sudo apt -y upgrade && sudo apt -y dist-upgrade

… This may take a while (15 ~ 30 minutes, depending on your bandwidth).

8. Install node

Now let’s install node and git. Git will allow you to fetch my sample code and node will allow you to run it.

This command will tell your Pi where to look for the node software:

curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -

Now install node:

sudo apt-get install -y nodejs

When the Pi has installed node, you can verify by checking the installed node version:

node -v

9. Install ILP dependencies

To be able to connect to Interledger (ILP), we’re going to install moneyd. To be able to receive money over ILP, we’re going to allow moneyd to connect to the XRP ledger. When we installed node, npm was also installed. npm is the Node Package Manager.

Let’s install moneyd and moneyd-uplink-xrp:

sudo npm install --unsafe-perm -g moneyd moneyd-uplink-xrp

If you see a few warnings (orange, yellow): no problem. Errors (red) are bad though.

10. Configure moneyd

Now let’s configure moneyd, so you can send and receive ILP payments. You will need 10 XRP of available XRP balance that will be locked in a Payment Channel (you can always close the Payment Channel and get your XRP back).

Please enter this command:

sudo moneyd xrp:configure --advanced

You’ll be asked four questions, you’ll need to manually enter two of them.

• BTP host: please enter client.scyl.la
• Name to assign to this channel: please leave as is
• XRP secret: please enter your own account XRPL (wallet) secret
• Rippled server: please leave as is

11. Install moneyd as a service

Now moneyd is configured, we want to configure a service, allowing moneyd to run in the background and auto-start when the Raspberry Pi boots.

Please copy-paste as is, and press enter:

sudo bash -c 'echo "[Unit]
Description=ILP provider using XRP payment channels
After=network.target nss-lookup.target
[Service]
ExecStart=/usr/bin/moneyd xrp:start
Restart=always
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=moneyd
User=root
Group=root
[Install]
WantedBy=multi-user.target" > /etc/systemd/system/moneyd-xrp.service'

Now let’s reload, so the Raspberry Pi is aware we just created a new service:

sudo systemctl daemon-reload

Now let’s enable the moneyd service:

sudo systemctl enable moneyd-xrp.service

… and finally: let’s start the moneyd service:

sudo systemctl start moneyd-xrp.service

Let’s wait ~20 seconds (so moneyd can start and connect) and check the logs:

sudo systemctl status moneyd-xrp.service

You should see a (partial) moneyd ASCII art banner and some more info;

Your Raspberry is now connected to ILP 🎉

12. Fetch and install the code

To receive ILP payments and send instructions (switch on / off) to your Raspberry Pi’s GPIO (General Purpose Input/Output) ports, you’ll need a piece of software I wrote. To fetch the code from Github, you’ll need to install git:

sudo apt install -y git

Now go to the home directory on your Raspberry Pi:

cd

… and clone my sample code from Github:

git clone https://github.com/WietseWind/RaspberryPi-ILP-GPIO.git

Now my code is cloned to the RaspberryPi-ILP-GPIO folder, let's go there:

cd RaspberryPi-ILP-GPIO

Rember npm, the node package manager, we used to install moneyd? We'll now use npm again, to install the dependencies (I didn't write all the code myself, I rely on packages by the awesome people at Interledger, etc.):

npm install

Now let’s run the code:

node index.js

If you want to run this code headless (in the background, at your own domain) you’ll need a follow-up tutorial, but for now, the code just generates a random hostname. This is your Payment Pointer. Money can be sent here (over ILP) 🎉

13. Note on reboots

When you reboot your Raspberry Pi, moneyd will auto-start since we've installed a service. The ILP receiver (my sample code, we just fetched from Git) will not run automatically, and will not run in the background, since you'll need to see the generated Payment Pointer.

If you reboot your Pi, you need to login again using SSH (step #6), go to the right folder again, and run it:

cd RaspberryPi-ILP-GPIO
node index.js

You will receive a new Payment Pointer every time you run the code again.

If you want to quit the code, press Control C a few times (on OSX, that’s alsoControl, not Command).

14. Wiring

So now the software is ready. Let’s get the hardware ready. Depending on your experience, this is either the easy or the scary part.

For the wiring, we’re using the GPIO connectors on the Raspberry Pi. The GPIO (General Purpose Input/Output) connector contains 40 pins. We’re only going to use three of them,

• The 3.3 volt pin
• The GPIO4 pin
• The GND pin

The external relay 3.3v relay board will also have 3 pins we’ll connect:

• 3.3v / Vcc
• IN1/Signal
• GND

The code from Step #12 instructs the Raspberry Pi to switch on/off the GP4 pin. The GP4 pin will either send no power or 3.3v, depending on if an ILP payment is coming in.

Since you can’t power a wall socket with 3.3v, we’ll switch a relay, that will switch the high(er) voltage wall socket / device.

If you don’t want to work with high voltage, you can also connect a low voltage (3.3v, or use a resistor) LED to the GP4 and GND connectors.

15. What’s next

I can think of a few things (not covered by this tutorial):

• Sending money, so your device will power on
• Running the ILP receiver in the background
• Running the Payment Pointer on your own (persistent) hostname, instead of a random localtunnel.me hostname
• Additional GPIO connectivity (inputs / outputs)
• Determine power usage and adjust ILP payments

I hope other community members will continue developing, sharing, blogging, etc. but I’d be happy to write follow-up blogs on these subjects… To be continued, by me, or by others ;)?

Thank you, @byrawpixel for the cover photo. Thanks to all XRPL, Interledger and Raspberry developers for allowing me to create awesome stuff :)