#  Raspberry Pi GPIO access using file descriptors.

'''The sysfs interface for user control of GPIO pins is
deprecated, and may ultimately be removed.  It is replaced
by a file descriptor interface that uses ioctl calls.
This module provides access to this newer GPIO facility.


GPIO device files, such as /dev/gpiochip0, by default allow
access only by root.  Execution of Python programs by root
is possible, but carries unnecesary risk.  A better plan is
to change permissions for the device file to allow all users
(or only users in a particular group) to access the device.

For example, when executed by root, this command:
   chmod a+rw /dev/gpiochip0
allows any user access to this GPIO device, without super-user 
privilege.

To allow access to users in a particular group:
   chmod g+rw /dev/gpiochip0
   chgrp dialout /dev/gpiochip0
will allow any user in the dialout group to access /dev/gpiochip0.
See the man pages for newgrp (change the group of the current login session)
and usermod (to add a user to a suplementary group so newgrp can
change to that group.)

This example used the "dialout" group because it already exists in
typical linux systems.  A new group, such as "gpio", could be defined
if "dialout" seems inappropriate.

udev rules can be written to set the default permissions for
a device file such as /dev/gpiochip0 during boot.  Example:
________________________________________________________________________________

#  File:  /etc/udev/rules.d/20_gpio.rules

SUBSYSTEM=="gpio", DEVPATH=="/devices/platform/soc/3f200000.gpio/gpiochip0", ACTION=="add", GROUP="dialout", MODE="0660"
________________________________________________________________________________

or MODE="0666" would allow access to every user without limitation to
one group.


GPIO data access.

To reduce overhead, this module provides the pieces that allow a
user to call to read or write GPIO data using the file descripter
obtained from get_gpiohandle.

   FD = gpiofd.get_gpiohandle(...)
   DATA = gpiofd.get_data_arg()

   To read:     gpiofd.f_cntrl(FD, gpiofd.DATA_READ, DATA)
   To write:    gpiofd.f_cntrl(FD, gpiofd.DATA_WRITE, DATA)

Data values can be read/written from DATA
(this has length gpiofd.GPIOHANDLES_MAX, but only the first 
num_lines [from the call to gpiofd.get_gpiohandle] are used.)
Example:  DATA[0] = 1 sets an output pin on (off if GPIOLINE_FLAG_ACTIVE_LOW
                      was specified.)
          DATA[0] = b'\x00' if input is low (high if GPIOLINE_FLAG_ACTIVE_LOW
                            was specified.)


Complete example:  a blink program.
________________________________________________________________________________

#!/usr/bin/python3

import gpiofd, time

count = 30     # Number of output changes (blinks will be half this number.)
pin   = 23     # The GPIO output pin.

# Could add optional argument to the following:  label = b'blink'
g = gpiofd.get_gpiohandle('/dev/gpiochip0', (pin,), gpiofd.GPIOHANDLE_REQUEST_OUTPUT)
data = gpiofd.get_data_arg()
func = gpiofd.f_ioctl
x = 0
data[0] = 1
while x < count:
    x += 1
    func(g, gpiofd.DATA_WRITE, data)
    if data[0] == b'\00':
        data[0] = 1
    else:
        data[0] = 0
    time.sleep(1)
________________________________________________________________________________


Another example:  monitor input signal on a GPIO pin
                  and display state changes:
________________________________________________________________________________

#!/bin/python3

# Monitor GPIO pin 24.

import sys, select
import gpiofd

device = '/dev/gpiochip0'
pin = 24
event_names = ['Zero! (error)', 'Rising edge', 'Falling edge']

event_fd = gpiofd.get_event(device, pin, 0, gpiofd.GPIOEVENT_REQUEST_RISING_EDGE | gpiofd.GPIOEVENT_REQUEST_FALLING_EDGE, label=b'gpio_monitor.py')
ep = select.epoll()
ep.register(event_fd, select.EPOLLIN)
sys.stdout.write('Waiting for events on GPIO pin {}\n'.format(pin))
while True:
    ep.poll()
    (timestamp, event) = gpiofd.get_event_data(event_fd)
    sys.stdout.write('{:24.9f}  {:d}  {}\n'.format(timestamp, event, event_names[event]))
________________________________________________________________________________

Written by:  Richard Ryniker  <ryniker@alum.mit.edu>
April 10, 2017

'''

import sys, os, ctypes, ctypes.util
from utils import dump_memory

class gpiofd_error(IOError):
    def __init__(self, errno):
        self.errno = errno

libc = ctypes.CDLL(ctypes.util.find_library('c'))
f_ioctl = libc.ioctl
f_read = libc.read

#################################################
# ioctl construction functions.
# Derived from asm-generic/ioctl.h

sizebits  = 14
dirbits   = 2
nrbits    = 8
typebits  = 8
nrshift   = 0
typeshift = nrshift + nrbits
sizeshift = typeshift + typebits
dirshift  = sizeshift + sizebits

ioc_read = 2
ioc_write = 1


def IOC(dir, t, nr, size):
    
    x = dir<<dirshift | t<<typeshift | nr<<nrshift | size<<sizeshift
    #sys.stdout.write('IOC = {:08X}\n'.format(x))
    return x
    
def IOR(t, nr, size):
    return IOC(ioc_read, t, nr, size)
    
def IOW(t, nr, size):
    return IOC(ioc_write, t, nr, size)

def IOWR(t, nr, size):
    return IOC(ioc_write | ioc_read, t, nr, size)

#################################################
# Values from linux/gpio.h

GPIOHANDLES_MAX             =  64

GPIOLINE_FLAG_KERNEL        =   1 << 0  # Line used by the kernel.
GPIOLINE_FLAG_IS_OUT        =   1 << 1
GPIOLINE_FLAG_ACTIVE_LOW    =   1 << 2
GPIOLINE_FLAG_OPEN_DRAIN    =   1 << 3
GPIOLINE_FLAG_OPEN_SOURCE   =   1 << 4

GPIOHANDLE_REQUEST_INPUT	= 1 << 0
GPIOHANDLE_REQUEST_OUTPUT	= 1 << 1
GPIOHANDLE_REQUEST_ACTIVE_LOW	= 1 << 2
GPIOHANDLE_REQUEST_OPEN_DRAIN	= 1 << 3
GPIOHANDLE_REQUEST_OPEN_SOURCE	= 1 << 4

GPIOEVENT_REQUEST_RISING_EDGE	= 1 << 0
GPIOEVENT_REQUEST_FALLING_EDGE	= 1 << 1
GPIOEVENT_REQUEST_BOTH_EDGES	= GPIOEVENT_REQUEST_RISING_EDGE	| GPIOEVENT_REQUEST_FALLING_EDGE

GPIOEVENT_EVENT_RISING_EDGE  = 1
GPIOEVENT_EVENT_FALLING_EDGE = 2



#################################################

c32    = ctypes.c_char * 32
cul_MAX = ctypes.c_ulong * GPIOHANDLES_MAX
cu8_MAX = ctypes.c_ubyte * GPIOHANDLES_MAX

def open_device(fd):
    if not isinstance(fd, int):
        fd = os.open(fd, os.O_RDWR)
        if fd <0:
            raise gpiofd_error(fd)
    return fd

    
def maybe_close_fd(fd, fdx):
    '''Many functions in this module accept either a file descriptor or
a path name to identify a GPIO chip.  If a path name is supplied, it
will be opened in order to obtain the file descriptor (fdx) needed for calls
to ioctl.  This maybe_close_fd function examines its fd argument
(either a path name or integer file descriptor) and, if fd is not
a file descriptor, will close the file descriptor fdx
opened when a path name was supplied as fd. '''
    if not isinstance(fd, int):
        os.close(fdx)


def bytes_until_null(ints):
    '''Iterate through ints until a zero value,
and return a bytestring that contains the earlier items.'''
    x = 0
    z = len(ints)
    while x < z:
        if ints[x] == 0:
            break
        x += 1
    return bytes(ints[0:x])


class gpiochip_info (ctypes.Structure):
    _fields_ = [("name", c32),
                ("label", c32),
                ("lines", ctypes.c_long)]

def get_gpiochip_info(fd):
    '''Return chip information.  fd may be either a path,
such as /dev/gpiochip0 or a file descriptor opened for
such a device.

Value is a 3-tuple: (number of GPIO lines on this chip, b'name', b'label')
'''

    fdx = open_device(fd)
        
    info = gpiochip_info()

    cfd = ctypes.c_int(fdx)
    ioc = ctypes.c_ulong(IOR(0xB4, 0x01, ctypes.sizeof(info)))

    rc = f_ioctl(cfd, ioc, ctypes.byref(info))
    if rc != 0:
        raise gpiofd_error(rc)

    maybe_close_fd(fd, fdx)
    return (info.lines, bytes_until_null(info.name), bytes_until_null(info.label))


class gpioline_info (ctypes.Structure):
    _fields_ = [("line", ctypes.c_long),
                ("flags", ctypes.c_ulong),
                ("name", c32),
                ("consumer", c32)
                ]

def get_gpioline_info(fd, line):
    '''Return line information.  fd may be either a path,
such as /dev/gpiochip0 or a file descriptor opened for
such a device.

0 <= line < number of lines on chip.

Value is a 3-tuple: (flags, b'name', b'consumer')
'''
    
    fdx = open_device(fd)
    info = gpioline_info()
    info.line = line
    ioc = ctypes.c_ulong(IOWR(0xB4, 0x02, ctypes.sizeof(info)))
    rc = f_ioctl(ctypes.c_int(fdx), ioc, ctypes.byref(info))
    if rc != 0:
        raise gpiofd_error(rc)

    maybe_close_fd(fd, fdx)
    return (info.flags, bytes_until_null(info.name), bytes_until_null(info.consumer))


class gpiohandle_request (ctypes.Structure):
    _fields_ = [('lineoffsets', cul_MAX),     # Specific lines requested from this GPIO chip.
	        ('flags', ctypes.c_ulong),    # Line characteristics (all lines the same).
	        ('default_values', cu8_MAX),
	        ('consumer_label', c32),
	        ('lines', ctypes.c_ulong),    # Number of elements used in the lineoffsets and default_values arrays.
	        ('fd', ctypes.c_int)]


def get_gpiohandle(fd, offsets, flags, defaults = None, label= b'', num_lines = 1):
    '''Returns a file descriptor for a set of GPIO lines on the GPIO chip
associated with fd.

offsets is a sequence (or other type that supports indexing) that supplies integers to specify
which lines are desired; these integers must be in the range from 0 to one less than
the number of GPIO lines implemented on the chip (a value supplied by the 
get_gpiochip_data function.)

flags are defined by or'ing GPIOHANDLE_REQUEST_* values.

If GPIOHANDLE_REQUEST_OUTPUT is specified in flags, the defaults iterable
may be used to set whether the default (initial) value is on (value is 1)
or off (value is 0).
Default for initial values is off.

The label argument, if used, should be a byte string that
identifies the application or use for these pins.  This string will
appear in the information returned by get_gpioline_info (until the
file descriptor for these pins is closed.)

num_lines specifies how many lines are desired; default value is 1.
This many values must be supplied by the offsets and, if specified,
the defaults arguments.
'''

    if defaults == None:
        defaults = (0,) * num_lines
    req = gpiohandle_request(consumer_label=label, default_values = defaults)
    if GPIOHANDLES_MAX < num_lines:
        raise gpiofd_error('number of lines too large')
    for k in range(num_lines):
        req.lineoffsets[k] = offsets[k]
    req.flags = flags
    req.lines = num_lines
    if flags & GPIOHANDLE_REQUEST_OUTPUT and defaults:
        for k in range(num_lines):
            req.default_values[k ] = defaults[k]
    fdx = open_device(fd)
    ioc = ctypes.c_ulong(IOWR(0xB4, 0x03, ctypes.sizeof(req)))
    #dump_memory(ctypes.addressof(req), ctypes.sizeof(req))
    rc = f_ioctl(fdx, ioc, ctypes.byref(req))
    if rc != 0:
        sys.stderr.write('gpiofd.get_gpiohandle ioctl error {}\n'.format(rc))
        raise gpiofd_error(rc)

    maybe_close_fd(fd, fdx)
    return req.fd


DATA_READ  = IOWR(0xB4, 0x08, GPIOHANDLES_MAX)
DATA_WRITE = IOWR(0xB4, 0x09, GPIOHANDLES_MAX)


def get_data_arg():
    '''Return an object used to read or write values for the pins
controlled by a gpiohandle. '''
    return ctypes.create_string_buffer(GPIOHANDLES_MAX)


class gpioevent_request (ctypes.Structure):
    _fields_ = [('lineoffset', ctypes.c_ulong),     # Line requested from this GPIO chip.
	        ('handleflags', ctypes.c_ulong),    # Line characteristics, e.g. GPIOHANDLE_REQUEST_ACTIVE_LOW.
	        ('eventflags', ctypes.c_ulong),     # Desired event types, e.g. GPIOEVENT_REQUEST_RISING_EDGE
	        ('consumer_label', c32),
	        ('fd', ctypes.c_int)]

def get_event(fd, offset, handleflags, events, label = None):
    '''Return a file descriptor to receive event notifications for the specified GPIO pin.
This file descriptor may be used with select, epoll, etc. to wait until input is ready.
When ready, get_event_data(fd)  will return the event data.

Arguments:  fd          is a path (such as /dev/gpiochip0) or a file descriptor open
                        for such a path, that identifies a GPIO device.
            offset      denotes the GPIO pin for which events will be reported,
                        on the GPIO device specified by argument fd.
            handleflags specifies characteristics auch as GPIOHANDLE_REQUEST_ACTIVE_LOW.
            events      says what events are desired, e.g. GPIOEVENT_REQUEST_BOTH_EDGES.
            label       Optional byte string to identify the user of this GPIO pin,
                        for example b'app1 limit interrupt'. 
'''
    if label == None:
        label = b''
    request = gpioevent_request(offset, handleflags, events, label)
    fdx = open_device(fd)
    ioc = ctypes.c_ulong(IOWR(0xB4, 0x04, ctypes.sizeof(request)))
    rc = f_ioctl(fdx, ioc, ctypes.byref(request))
    if rc != 0:
        sys.stderr.write('gpiofd.get_event ioctl error {}\n'.format(rc))
        raise gpiofd_error(rc)
    maybe_close_fd(fd, fdx)
    return request.fd


class gpioevent_data(ctypes.Structure):
    _fields_ = [('timestamp', ctypes.c_ulonglong),   # Nanoseconds.
	        ('event', ctypes.c_ulong)]
    

def get_event_data(fd):
    '''Read event data from FD and return the 2-tuple (tiem_stamp, event_type)
where time_stanp is time of the event (seconds since start of the epoch)
and event_type is either GPIOEVENT_EVENT_RISING_EDGE or GPIOEVENT_EVENT_FALLING_EDGE
'''
    d = gpioevent_data()
    rc = f_read(fd, ctypes.byref(d), ctypes.sizeof(d))
    if rc != ctypes.sizeof(d):
        sys.stderr.write('gpiofd.get_event_data error\n')
        raise gpiofd.error()
    return ( float(d.timestamp) / 1e9, d.event)