# uCOMmandIt Interrupt Package for SBC GPio Pins

<!-- find and replace the package name to match -->
[![Build Status](https://img.shields.io/travis/uCOMmandIt/uci-interrupt.svg?branch=master)](https://travis-ci.org/uCOMmandIt/uci-interrupt)
[![Inline docs](http://inch-ci.org/github/uCOMmandIt/uci-interrupt.svg?branch=master)](http://inch-ci.org/github/uCOMmandIt/uci-interrupt)
[![devDependencies](https://img.shields.io/david/dev/uCOMmandIt/uci-interrupt.svg)](https://david-dm.org/uCOMmandIt/uci-interrupt?type=dev)
[![codecov](https://img.shields.io/codecov/c/github/uCOMmandIt/uci-interrupt/master.svg)](https://codecov.io/gh/uCOMmandIt/uci-interrupt)

This module creates an instance of UCI Packect Interrupt class for a SBC gpio pin supporting interrupt via epoll (kernel gpio/export) by extending the UCI base class.

Each pin will create it's own socket (based on options pased)  By default it will create a tcp socket at 9000+pin number.  I can create a socket for all transports.

When a gpio pin so set up is tripped this class pushes a UCI packet to all connected consumers.

You can pass a custom packet to push via the options and/or ammend the basic packet via a hook you provide.

By default the packet will send and packet.cmd='interrupt' but you can customize that via either passing .cmd in the .packet option or passing .pushCmd

UCI tcp and pipe transports sockets support an initial connection packet sent to connecting consumers by by passing .conPacket= { } or .resetCmd=  to instance.
This allows one to take some initial action related to interrupt (e.g. an mcp chip can reset it's interrupt connect to a sbc gpio pin)

## Set up hardware GPio bus pins as interrupts for use with UCI Interrupt

### Enable access to GPios
make sure your user is in the `gpio` group

Give `gpio` group permission to reading/writing from/to pins.  On raspbien installs this should already work for pi user.  For other distros and other hardware the following rule put in a file in `/etc/udev/rules.d/` should work.

```
SUBSYSTEM=="gpio*", PROGRAM="/bin/sh -c 'find -L /sys/class/gpio/ -maxdepth 2 -exec chown root:gpio {} \; -exec chmod 770 {} \; || true'"
```

if you get permission errors then likely this rule is not effective.  Take a look at /sys/class/gpio folder and see if gpio group has been added appropriately (e.g. to /export and /unexport).   

### Set hardware pull

You must tell the gpio bus hardware about which pins you want to use as interrupts and what pull state you want.  This only needs to be done once and is somewhat specific to the sbc you are using.

#### Raspberry Pi
For raspberry pi with recent distro/kernel (e.g. Ubuntu 18.04,mainline 4.15) you can use add a line to config.txt in /boot or subdir therein. Add a line like this

`gpio=9,10,24=pd`

 The pin defaults can be seen in Table 6-31 on pages 102 and 103 of the [BCM2835 ARM Peripherals](http://www.farnell.com/datasheets/1521578.pdf) documentation.

Other possible [settings](https://www.raspberrypi.org/forums/viewtopic.php?f=117&t=208748) are
```
      ip - Input
      op - Output
      a0-a5 - Alt0-Alt5
      dh - Driving high (for outputs)
      dl - Driving low (for outputs)
      pu - Pull up
      pd - Pull down
      pn/np - No pull
```

#### Other SBC GPio buses

For other SBCs with a gpio bus you'll need to consult the manufactuer docs/forum but you should be able to create and add device tree blobs to set the gpio pins. It may involve enabling device tree overlays and installing the dto package, etc.  Here is a [How to for the Raspberry Pi](https://github.com/fivdi/onoff/wiki/Enabling-Pullup-and-Pulldown-Resistors-on-The-Raspberry-Pi) which of course is not necessary (see above) but will give you a start on other hardware

Example dts file for raspberry pi
```
/dts-v1/;
/plugin/;

/ {
    compatible = "brcm,bcm2708";

    fragment@0 {
        target = <&gpio>;
        __overlay__ {
            pinctrl-names = "default";
            pinctrl-0 = <&my_pins>;

            my_pins: my_pins {
                brcm,pins = <7 8 9>;     /* gpio no. */
                brcm,function = <0 0 0>; /* 0:in, 1:out */
                brcm,pull = <1 1 2>;     /* 2:up 1:down 0:none */
            };
        };
    };
};
```