# ContactPi
Use buttons connected to a Rasberry Pi GPIO to trigger Hog 4 comment macros.

> If you are new to Raspberry Pi consider reading some [brief introductory tips.](https://thepihut.com/blogs/raspberry-pi-tutorials/the-raspberry-pi-tutorial-beginners-guide)

## Preparing the Raspberry Pi

*   Install Raspbian [the usual way.](https://www.raspberrypi.org/documentation/installation/installing-images/README.md)

* Enable the ssh server.
  - On a Mac within the terminal:
  ```
  > touch /Volumes/boot/ssh
  ```
  - On Windows:
      1. Go to the boot folder created on the SD card
      2. Create a blank text document named SSH


* Eject the SD card and boot the Raspberry Pi.

*   Use SSH to log into the Pi from your computers Command Line (Windows) or Terminal (Mac):
```
> ssh pi@PI_IP_ADDRESS
```
* The default password is `raspberry`.

* Use `sudo raspi-config` to;
    - set locale
    - set timezone
    - enlarge the file-system to fill the SD card
    - reboot


* Update the package manager and install the aptitude program.
```
> sudo apt-get update
> sudo apt-get install aptitude
```

*   Use aptitude to upgrade the Pi.
```
> sudo aptitude upgrade
```

*   Reboot the Pi.
```
> sudo shutdown -r now
```

*   Logging back into the Pi, install sane set of software packages.
```
> sudo aptitude install git python3-pip python3-gpiozero
> sudo pip3 install gpiozero antlr4-python3-runtime python-osc
```

## Installing

* Change directory into `/home/pi`:
```
> cd /home/pi
```
> If you didn't notice any change you might already be in the correct directory.  You can confirm this by using the command `pwd` to print the  working directory. It should print: `/home/pi`

* Download ContactPi:
```
> git clone --recurse-submodules https://git.company235.com/kevin/ContactPi.git
```

* Change directory into ContactPi:
 ```
> cd ContactPi
```

## Enabling on Boot

* Link the service file to systemd:
```
> sudo cp buttons.service /lib/systemd/system/buttons.service
```

* Enable the service at startup:
```
> sudo systemctl daemon-reload
> sudo systemctl enable buttons.service
```

* Start the buttons service:
```
> sudo systemctl start buttons.service
```

## Hardware Setup

* Connect one side of the button to ground, the other to a GPIO pin.

![](https://gpiozero.readthedocs.io/en/stable/_images/button_bb.svg)

You may use any of the numbered GPIO pins available on the PI:

![](https://www.raspberrypi.org/documentation/usage/gpio/images/GPIO.png)

## Configuring

### Buttons and Macros

>Nano is a command line text editor that is available by default on the Pi.  For a usage overview, read [The Beginner's Guide to Nano](https://www.howtogeek.com/howto/42980/the-beginners-guide-to-nano-the-linux-command-line-text-editor/)


* Use nano to configure the pinout and macro settings.
```
> nano buttons.cfg
```

  This file configures which Raspberry Pi GPIO pins trigger which comment macros.

  The `button` section contains a comma separated list of named button sections.

  This is a sample buttons.cfg file:
  ```
  [button]
  names=switch1,switch2,switch3,switch4

  [switch1]
  pin: 12
  close: "gl21/2"
  open: "gl21/1"

  [switch2]
  pin: 16
  close: "gl22/2"
  open: "gl22/1"

  [switch3]
  pin: 20
  close: "gl23/2"
  open: "gl23/1"

  [switch4]
  pin: 21
  close: "gl24/2"
  open: "gl24/1"
  ```

> ContactPi uses [Bacon Script](https://git.company235.com/kevin/baconscript) to abstract the underlying OSC. The [README](https://git.company235.com/kevin/baconscript/src/branch/master/README.md) file of that project contains additional details about the syntax for configuring comment macros.

* Once the file has been configured press `ctrl+x` to exit.

### Hog Servers

* Use nano to configure the Hog server settings.
```
> nano server.cfg
```

  > Contact Pi only sends OSC commands to the first server in this list unless the net number is explicitly specified in the comment macro.
  > `EXAMPLEh22`.

  This is a sample server.cfg file:
  ```
  [network]
  hogs = hog4_235, hedgehog_235, server_pc, server_rackhog

  [hog4_235]
  ip: 10.235.1.53
  port: 7001
  net: 53

  [hedgehog_235]
  ip: 10.235.1.63
  port: 7001
  net: 63

  [server_pc]
  ip: 10.235.1.12
  port: 7001
  net: 12

  [server_rackhog]
  ip: 10.235.1.22
  port: 7001
  net: 22
  ```


* Once the file has been configured `ctrl+x` to exit.

* Restart buttons.service to apply changes.
```
> sudo systemctl restart buttons.service
```

* Check the status of the `buttons` systemd service.
```
> sudo systemctl status buttons.service

  ● buttons.service - OSC Button Watcher
     Loaded: loaded (/lib/systemd/system/buttons.service; enabled; vendor preset: enabled)
     Active: active (running) since Fri 2020-11-20 14:27:43 EST; 3s ago
   Main PID: 1032 (python3)
      Tasks: 6 (limit: 1433)
     CGroup: /system.slice/buttons.service
             └─1032 /usr/bin/python3 /home/pi/ContactPi/buttond.py

             Nov 20 14:27:43 raspberrypi systemd[1]: Started OSC Button Watcher.
             Nov 20 14:27:43 raspberrypi python3[1032]: Adding Hog device at net# 53
             Nov 20 14:27:43 raspberrypi python3[1032]: Adding Hog device at net# 63
             Nov 20 14:27:43 raspberrypi python3[1032]: Adding Hog device at net# 12
             Nov 20 14:27:43 raspberrypi python3[1032]: Adding Hog device at net# 22
  ```