V57

1 files changed, 538 insertions, 38 deletions

diff --git a/pigpio.py b/pigpio.py
index b0962d5..b22202e 100644
--- a/pigpio.py
+++ b/pigpio.py
@@ -56,7 +56,7 @@ If you wish to handle the returned status yourself you should set
 pigpio.exceptions to False.
 
 You may prefer to check the returned status in only a few parts
-of your code.  In that case do the following.
+of your code.  In that case do the following:
 
 ...
 pigpio.exceptions = False
@@ -242,6 +242,11 @@ bb_spi_open               Opens GPIO for bit banging SPI
 bb_spi_close              Closes GPIO for bit banging SPI
 bb_spi_xfer               Transfers bytes with bit banging SPI
 
+I2C/SPI_Slave
+
+bsc_xfer                  I2C/SPI as slave transfer
+bsc_i2c                   I2C as slave transfer
+
 Serial
 
 serial_open               Opens a serial device
@@ -264,6 +269,12 @@ file_write                Writes bytes to a file
 file_seek                 Seeks to a position within a file
 file_list                 List files which match a pattern
 
+Events
+
+event_callback            Sets a callback for an event
+event_trigger             Triggers an event
+wait_for_event            Wait for an event
+
 Custom
 
 custom_1                  User custom function 1
@@ -288,7 +299,7 @@ import threading
 import os
 import atexit
 
-VERSION = "1.33"
+VERSION = "1.34"
 
 exceptions = True
 
@@ -337,6 +348,7 @@ PI_SCRIPT_FAILED =4
 
 # notification flags
 
+NTFY_FLAGS_EVENT = (1 << 7)
 NTFY_FLAGS_ALIVE = (1 << 6)
 NTFY_FLAGS_WDOG  = (1 << 5)
 NTFY_FLAGS_GPIO  = 31
@@ -376,6 +388,8 @@ SPI_CS_HIGH_ACTIVE  = 1 << 2
 SPI_TX_LSBFIRST = 1 << 14
 SPI_RX_LSBFIRST = 1 << 15
 
+EVENT_BSC = 31
+
 # pigpio command numbers
 
 _PI_CMD_MODES= 0
@@ -518,6 +532,11 @@ _PI_CMD_BSPIC=111
 _PI_CMD_BSPIO=112
 _PI_CMD_BSPIX=113
 
+_PI_CMD_BSCX =114
+
+_PI_CMD_EVM  =115
+_PI_CMD_EVT  =116
+
 # pigpio error numbers
 
 _PI_INIT_FAILED     =-1
@@ -663,6 +682,7 @@ PI_BAD_SHELL_STATUS =-139
 PI_BAD_SCRIPT_NAME  =-140
 PI_BAD_SPI_BAUD     =-141
 PI_NOT_SPI_GPIO     =-142
+PI_BAD_EVENT_ID     =-143
 
 # pigpio error text
 
@@ -807,13 +827,14 @@ _errors=[
    [PI_BAD_SCRIPT_NAME   , "bad script name"],
    [PI_BAD_SPI_BAUD      , "bad SPI baud rate, not 50-500k"],
    [PI_NOT_SPI_GPIO      , "no bit bang SPI in progress on GPIO"],
+   [PI_BAD_EVENT_ID      , "bad event id"],
 ]
 
-except_a = "%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n{}"
+_except_a = "%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n{}"
 
-except_z = "%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%"
+_except_z = "%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%"
 
-except1 = """
+_except_1 = """
 Did you start the pigpio daemon? E.g. sudo pigpiod
 
 Did you specify the correct Pi host/port in the environment
@@ -823,7 +844,7 @@ E.g. export PIGPIO_ADDR=soft, export PIGPIO_PORT=8888
 Did you specify the correct Pi host/port in the
 pigpio.pi() function? E.g. pigpio.pi('soft', 8888)"""
 
-except2 = """
+_except_2 = """
 Do you have permission to access the pigpio daemon?
 Perhaps it was started with sudo pigpiod -nlocalhost"""
 
@@ -981,6 +1002,22 @@ def _pigpio_command_ext(sl, cmd, p1, p2, p3, extents, rl=True):
    if rl: sl.l.release()
    return res
 
+class _event_ADT:
+   """
+   An ADT class to hold event callback information.
+   """
+
+   def __init__(self, event, func):
+      """
+      Initialises an event callback ADT.
+
+      event:= the event id.
+       func:= a user function taking one argument, the event id.
+      """
+      self.event = event
+      self.func = func
+      self.bit = 1<<event
+
 class _callback_ADT:
    """An ADT class to hold callback information."""
 
@@ -1007,7 +1044,9 @@ class _callback_thread(threading.Thread):
       self.go = False
       self.daemon = True
       self.monitor = 0
+      self.event_bits = 0
       self.callbacks = []
+      self.events = []
       self.sl.s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
       self.sl.s.settimeout(None)
       self.sl.s.connect((host, port))
@@ -1039,6 +1078,28 @@ class _callback_thread(threading.Thread):
             _pigpio_command(
                self.control, _PI_CMD_NB, self.handle, self.monitor)
 
+   def append_event(self, callb):
+      """
+      Adds an event callback to the notification thread.
+      """
+      self.events.append(callb)
+      self.event_bits = self.event_bits | callb.bit
+      _pigpio_command(self.control, _PI_CMD_EVM, self.handle, self.event_bits)
+
+   def remove_event(self, callb):
+      """
+      Removes an event callback from the notification thread.
+      """
+      if callb in self.events:
+         self.events.remove(callb)
+         new_event_bits = 0
+         for c in self.events:
+            new_event_bits |= c.bit
+         if new_event_bits != self.event_bits:
+            self.event_bits = new_event_bits
+            _pigpio_command(
+               self.control, _PI_CMD_EVM, self.handle, self.event_bits)
+
    def run(self):
       """Runs the notification thread."""
 
@@ -1071,7 +1132,12 @@ class _callback_thread(threading.Thread):
                   gpio = flags & NTFY_FLAGS_GPIO
                   for cb in self.callbacks:
                      if cb.gpio == gpio:
-                        cb.func(cb.gpio, TIMEOUT, tick)
+                        cb.func(gpio, TIMEOUT, tick)
+               elif flags & NTFY_FLAGS_EVENT:
+                  event = flags & NTFY_FLAGS_GPIO
+                  for cb in self.events:
+                     if cb.event == event:
+                        cb.func(event, tick)
 
       self.sl.s.close()
 
@@ -1118,6 +1184,52 @@ class _callback:
       self._reset = True
       self.count = 0
 
+class _event:
+   """A class to provide event callbacks."""
+
+   def __init__(self, notify, event, func=None):
+      """
+      Initialise an event and adds it to the notification thread.
+      """
+      self._notify = notify
+      self.count=0
+      self._reset = False
+      if func is None:
+         func=self._tally
+      self.callb = _event_ADT(event, func)
+      self._notify.append_event(self.callb)
+
+   def cancel(self):
+      """
+      Cancels a event callback by removing it from the
+      notification thread.
+      """
+      self._notify.remove_event(self.callb)
+
+   def _tally(self, event, tick):
+      """Increment the event callback called count."""
+      if self._reset:
+         self._reset = False
+         self.count = 0
+      self.count += 1
+
+   def tally(self):
+      """
+      Provides a count of how many times the default tally
+      callback has triggered.
+
+      The count will be zero if the user has supplied their own
+      callback function.
+      """
+      return self.count
+
+   def reset_tally(self):
+      """
+      Resets the tally count to zero.
+      """
+      self._reset = True
+      self.count = 0
+
 class _wait_for_edge:
    """Encapsulates waiting for GPIO edges."""
 
@@ -1136,6 +1248,24 @@ class _wait_for_edge:
       """Sets wait_for_edge triggered."""
       self.trigger = True
 
+class _wait_for_event:
+   """Encapsulates waiting for an event."""
+
+   def __init__(self, notify, event, timeout):
+      """Initialises wait_for_event."""
+      self._notify = notify
+      self.callb = _event_ADT(event, self.func)
+      self.trigger = False
+      self._notify.append_event(self.callb)
+      self.start = time.time()
+      while (self.trigger == False) and ((time.time()-self.start) < timeout):
+         time.sleep(0.05)
+      self._notify.remove_event(self.callb)
+
+   def func(self, event, tick):
+      """Sets wait_for_event triggered."""
+      self.trigger = True
+
 class pi():
 
    def _rxbuf(self, count):
@@ -1501,7 +1631,7 @@ class pi():
       E.g. if the function returns 15 then the notifications must be
       read from /dev/pigpio15.
 
-      Notifications have the following structure.
+      Notifications have the following structure:
 
       . .
       H seqno
@@ -1513,16 +1643,20 @@ class pi():
       seqno: starts at 0 each time the handle is opened and then
       increments by one for each report.
 
-      flags: two flags are defined, PI_NTFY_FLAGS_WDOG and
-      PI_NTFY_FLAGS_ALIVE.
+      flags: three flags are defined, PI_NTFY_FLAGS_WDOG,
+      PI_NTFY_FLAGS_ALIVE, and PI_NTFY_FLAGS_EVENT.
 
-      PI_NTFY_FLAGS_WDOG, if bit 5 is set then bits 0-4 of the
+      If bit 5 is set (PI_NTFY_FLAGS_WDOG) then bits 0-4 of the
       flags indicate a GPIO which has had a watchdog timeout.
 
-      PI_NTFY_FLAGS_ALIVE, if bit 6 is set this indicates a keep
+      If bit 6 is set (PI_NTFY_FLAGS_ALIVE) this indicates a keep
       alive signal on the pipe/socket and is sent once a minute
       in the absence of other notification activity.
 
+      If bit 7 is set (PI_NTFY_FLAGS_EVENT) then bits 0-4 of the
+      flags indicate an event which has been triggered.
+
+
       tick: the number of microseconds since system boot.  It wraps
       around after 1h12m.
 
@@ -1732,7 +1866,7 @@ class pi():
       The same clock is available on multiple GPIO.  The latest
       frequency setting will be used by all GPIO which share a clock.
 
-      The GPIO must be one of the following.
+      The GPIO must be one of the following:
 
       . .
       4   clock 0  All models
@@ -1783,7 +1917,7 @@ class pi():
       The latest frequency and dutycycle setting will be used
       by all GPIO which share a PWM channel.
 
-      The GPIO must be one of the following.
+      The GPIO must be one of the following:
 
       . .
       12  PWM channel 0  All models but A and B
@@ -2418,7 +2552,7 @@ class pi():
 
       For the SMBus commands the low level transactions are shown
       at the end of the function description.  The following
-      abbreviations are used.
+      abbreviations are used:
 
       . .
       S     (1 bit) : Start bit
@@ -3229,7 +3363,7 @@ class pi():
 
       ...
       (count, data) = pi.bb_i2c_zip(
-                         h, [4, 0x53, 2, 7, 1, 0x32, 2, 6, 6, 3, 0])
+                         SDA, [4, 0x53, 2, 7, 1, 0x32, 2, 6, 6, 3, 0])
       ...
 
       The following command codes are supported:
@@ -3293,6 +3427,261 @@ class pi():
       self.sl.l.release()
       return bytes, data
 
+   def event_trigger(self, event):
+      """
+      This function signals the occurrence of an event.
+
+      event:= 0-31, the event
+
+      Returns 0 if OK, otherwise PI_BAD_EVENT_ID.
+
+      An event is a signal used to inform one or more consumers
+      to start an action.  Each consumer which has registered an
+      interest in the event (e.g. by calling [*event_callback*]) will
+      be informed by a callback.
+
+      One event, EVENT_BSC (31) is predefined.  This event is
+      auto generated on BSC slave activity.
+
+      The meaning of other events is arbitrary.
+
+      Note that other than its id and its tick there is no data associated
+      with an event.
+
+      ...
+      pi.event_trigger(23)
+      ...
+      """
+      return _u2i(_pigpio_command(self.sl, _PI_CMD_EVT, event, 0))
+
+
+   def bsc_xfer(self, bsc_control, data):
+      """
+      This function provides a low-level interface to the
+      SPI/I2C Slave peripheral.  This peripheral allows the
+      Pi to act as a slave device on an I2C or SPI bus.
+
+      I can't get SPI to work properly.  I tried with a
+      control word of 0x303 and swapped MISO and MOSI.
+
+
+      The function sets the BSC mode, writes any data in
+      the transmit buffer to the BSC transmit FIFO, and
+      copies any data in the BSC receive FIFO to the
+      receive buffer.
+
+      bsc_control:= see below
+             data:= the data bytes to place in the transmit FIFO.
+
+      The returned value is a tuple of the status (see below),
+      the number of bytes read, and a bytearray containing the
+      read bytes.  If there was an error the status will be less
+      than zero (and will contain the error code).
+
+      Note that the control word sets the BSC mode.  The BSC will
+      stay in that mode until a different control word is sent.
+
+      The BSC peripheral uses GPIO 18 (SDA) and 19 (SCL)
+      in I2C mode and GPIO 18 (MOSI), 19 (SCLK), 20 (MISO),
+      and 21 (CE) in SPI mode.  You need to swap MISO/MOSI
+      between master and slave.
+
+      When a zero control word is received GPIO 18-21 will be reset
+      to INPUT mode.
+
+      bsc_control consists of the following bits:
+
+      . .
+      22 21 20 19 18 17 16 15 14 13 12 11 10  9  8  7  6  5  4  3  2  1  0
+       a  a  a  a  a  a  a  -  - IT HC TF IR RE TE BK EC ES PL PH I2 SP EN
+      . .
+
+      Bits 0-13 are copied unchanged to the BSC CR register.  See
+      pages 163-165 of the Broadcom peripherals document for full
+      details.
+
+      aaaaaaa @ defines the I2C slave address (only relevant in I2C mode)
+      IT      @ invert transmit status flags
+      HC      @ enable host control
+      TF      @ enable test FIFO
+      IR      @ invert receive status flags
+      RE      @ enable receive
+      TE      @ enable transmit
+      BK      @ abort operation and clear FIFOs
+      EC      @ send control register as first I2C byte
+      ES      @ send status register as first I2C byte
+      PL      @ set SPI polarity high
+      PH      @ set SPI phase high
+      I2      @ enable I2C mode
+      SP      @ enable SPI mode
+      EN      @ enable BSC peripheral
+
+      The status has the following format:
+
+      . .
+      20 19 18 17 16 15 14 13 12 11 10  9  8  7  6  5  4  3  2  1  0
+       S  S  S  S  S  R  R  R  R  R  T  T  T  T  T RB TE RF TF RE TB
+      . .
+
+      Bits 0-15 are copied unchanged from the BSC FR register.  See
+      pages 165-166 of the Broadcom peripherals document for full
+      details.
+
+      SSSSS @ number of bytes successfully copied to transmit FIFO
+      RRRRR @ number of bytes in receieve FIFO
+      TTTTT @ number of bytes in transmit FIFO
+      RB    @ receive busy
+      TE    @ transmit FIFO empty
+      RF    @ receive FIFO full
+      TF    @ transmit FIFO full
+      RE    @ receive FIFO empty
+      TB    @ transmit busy
+
+      ...
+      (status, count, data) = pi.bsc_xfer(0x330305, "Hello!")
+      ...
+      """
+      # I p1 control
+      # I p2 0
+      # I p3 len
+      ## extension ##
+      # s len data bytes
+
+      # Don't raise exception.  Must release lock.
+      bytes = u2i(_pigpio_command_ext(
+         self.sl, _PI_CMD_BSCX, bsc_control, 0, len(data), [data], False))
+      if bytes > 0:
+         rx = self._rxbuf(bytes)
+         status = struct.unpack('I', rx[0:4])[0]
+         bytes -= 4
+         data = rx[4:]
+      else:
+         status = bytes
+         bytes = 0
+         data = bytearray(b'')
+      self.sl.l.release()
+      return status, bytes, data
+
+   def bsc_i2c(self, i2c_address, data=[]):
+      """
+      This function allows the Pi to act as a slave I2C device.
+
+      The data bytes (if any) are written to the BSC transmit
+      FIFO and the bytes in the BSC receive FIFO are returned.
+
+      i2c_address:= the I2C slave address.
+             data:= the data bytes to transmit.
+
+      The returned value is a tuple of the status, the number
+      of bytes read, and a bytearray containing the read bytes.
+
+      See [*bsc_xfer*] for details of the status value.
+
+      If there was an error the status will be less than zero
+      (and will contain the error code).
+
+      Note that an i2c_address of 0 may be used to close
+      the BSC device and reassign the used GPIO (18/19)
+      as inputs.
+
+      This example assumes GPIO 2/3 are connected to GPIO 18/19.
+
+      ...
+      #!/usr/bin/env python
+      import time
+      import pigpio
+
+      I2C_ADDR=0x13
+
+      def i2c(id, tick):
+          global pi
+
+          s, b, d = pi.bsc_i2c(I2C_ADDR)
+          if b:
+              if d[0] == ord('t'): # 116 send 'HH:MM:SS*'
+
+                  print("sent={} FR={} received={} [{}]".
+                     format(s>>16, s&0xfff,b,d))
+
+                  s, b, d = pi.bsc_i2c(I2C_ADDR,
+                     "{}*".format(time.asctime()[11:19]))
+
+              elif d[0] == ord('d'): # 100 send 'Sun Oct 30*'
+
+                  print("sent={} FR={} received={} [{}]".
+                     format(s>>16, s&0xfff,b,d))
+
+                  s, b, d = pi.bsc_i2c(I2C_ADDR,
+                     "{}*".format(time.asctime()[:10]))
+
+      pi = pigpio.pi()
+
+      if not pi.connected:
+          exit()
+
+      # Respond to BSC slave activity
+
+      e = pi.event_callback(pigpio.EVENT_BSC, i2c)
+
+      pi.bsc_i2c(I2C_ADDR) # Configure BSC as I2C slave
+
+      time.sleep(600)
+
+      e.cancel()
+
+      pi.bsc_i2c(0) # Disable BSC peripheral
+
+      pi.stop()
+      ...
+
+      While running the above.
+
+      . .
+      $ i2cdetect -y 1
+          0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
+      00:          -- -- -- -- -- -- -- -- -- -- -- -- --
+      10: -- -- -- 13 -- -- -- -- -- -- -- -- -- -- -- --
+      20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+      30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+      40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+      50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+      60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+      70: -- -- -- -- -- -- -- --
+
+      $ pigs i2co 1 0x13 0
+      0
+
+      $ pigs i2cwd 0 116
+      $ pigs i2crd 0 9 -a
+      9 10:13:58*
+
+      $ pigs i2cwd 0 116
+      $ pigs i2crd 0 9 -a
+      9 10:14:29*
+
+      $ pigs i2cwd 0 100
+      $ pigs i2crd 0 11 -a
+      11 Sun Oct 30*
+
+      $ pigs i2cwd 0 100
+      $ pigs i2crd 0 11 -a
+      11 Sun Oct 30*
+
+      $ pigs i2cwd 0 116
+      $ pigs i2crd 0 9 -a
+      9 10:23:16*
+
+      $ pigs i2cwd 0 100
+      $ pigs i2crd 0 11 -a
+      11 Sun Oct 30*
+      . .
+      """
+      if i2c_address:
+         control = (i2c_address<<16)|0x305
+      else:
+         control = 0
+      return self.bsc_xfer(control, data)
+
    def spi_open(self, spi_channel, baud, spi_flags=0):
       """
       Returns a handle for the SPI device on channel.  Data will be
@@ -3545,6 +3934,8 @@ class pi():
 
       handle:= >=0 (as returned by a prior call to [*serial_open*]).
 
+      If no data is ready a negative error code will be returned.
+
       ...
       b = pi.serial_read_byte(h1)
       ...
@@ -3567,18 +3958,19 @@ class pi():
       return _u2i(
          _pigpio_command(self.sl, _PI_CMD_SERWB, handle, byte_val))
 
-   def serial_read(self, handle, count):
+   def serial_read(self, handle, count=1000):
       """
       Reads up to count bytes from the device associated with handle.
 
       handle:= >=0 (as returned by a prior call to [*serial_open*]).
-       count:= >0, the number of bytes to read.
+       count:= >0, the number of bytes to read (defaults to 1000).
 
-      The returned value is a tuple of the number of bytes read and a
-      bytearray containing the bytes.  If there was an error the
+      The returned value is a tuple of the number of bytes read and
+      a bytearray containing the bytes.  If there was an error the
       number of bytes read will be less than zero (and will contain
       the error code).
 
+      If no data is ready a bytes read of zero is returned.
       ...
       (b, d) = pi.serial_read(h2, 100)
       if b > 0:
@@ -4079,7 +4471,7 @@ class pi():
       Where more than one entry matches a file the most specific rule
       applies.  If no entry matches a file then access is denied.
 
-      Suppose /opt/pigpio/access contains the following entries
+      Suppose /opt/pigpio/access contains the following entries:
 
       . .
       /home/* n
@@ -4100,7 +4492,7 @@ class pi():
       may be created in that directory.
 
       In an attempt to prevent risky permissions the following paths are
-      ignored in /opt/pigpio/access.
+      ignored in /opt/pigpio/access:
 
       . .
       a path containing ..
@@ -4110,14 +4502,14 @@ class pi():
 
       Mode
 
-      The mode may have the following values.
+      The mode may have the following values:
 
       Constant   @ Value @ Meaning
       FILE_READ  @   1   @ open file for reading
       FILE_WRITE @   2   @ open file for writing
       FILE_RW    @   3   @ open file for reading and writing
 
-      The following values may be or'd into the mode.
+      The following values may be or'd into the mode:
 
       Name        @ Value @ Meaning
       FILE_APPEND @ 4     @ All writes append data to the end of the file
@@ -4137,7 +4529,7 @@ class pi():
       if not pi.connected:
          exit()
 
-      # Assumes /opt/pigpio/access contains the following line.
+      # Assumes /opt/pigpio/access contains the following line:
       # /ram/*.c r
 
       handle = pi.file_open("/ram/pigpio.c", pigpio.FILE_READ)
@@ -4284,7 +4676,7 @@ class pi():
       if not pi.connected:
          exit()
 
-      # Assumes /opt/pigpio/access contains the following line.
+      # Assumes /opt/pigpio/access contains the following line:
       # /ram/*.c r
 
       c, d = pi.file_list("/ram/p*.c")
@@ -4328,7 +4720,7 @@ class pi():
       the shell script exit function.  If the script can't be
       found 32512 will be returned.
 
-      The following table gives some example returned statuses.
+      The following table gives some example returned statuses:
 
       Script exit status @ Returned system call status
       1                  @ 256
@@ -4359,6 +4751,7 @@ class pi():
       return _u2i(_pigpio_command_ext(
          self.sl, _PI_CMD_SHELL, ls, 0, ls+lp+1, [shellscr+'\x00'+pstring]))
 
+
    def callback(self, user_gpio, edge=RISING_EDGE, func=None):
       """
       Calls a user supplied function (a callback) whenever the
@@ -4400,6 +4793,45 @@ class pi():
       """
       return _callback(self._notify, user_gpio, edge, func)
 
+   def event_callback(self, event, func=None):
+      """
+      Calls a user supplied function (a callback) whenever the
+      specified event is signalled.
+
+      event:= 0-31.
+       func:= user supplied callback function.
+
+      The user supplied callback receives two parameters, the event id,
+      and the tick.
+
+      If a user callback is not specified a default tally callback is
+      provided which simply counts events.  The count may be retrieved
+      by calling the tally function.  The count may be reset to zero
+      by calling the reset_tally function.
+
+      The callback may be cancelled by calling the event_cancel function.
+
+      An event may have multiple callbacks (although I can't think of
+      a reason to do so).
+
+      ...
+      def cbf(event, tick):
+         print(event, tick)
+
+      cb1 = pi.event_callback(22, cbf)
+
+      cb2 = pi.event_callback(4)
+
+      print(cb2.tally())
+
+      cb2.reset_tally()
+
+      cb1.event_cancel() # To cancel callback cb1.
+      ...
+      """
+
+      return _event(self._notify, event, func)
+
    def wait_for_edge(self, user_gpio, edge=RISING_EDGE, wait_timeout=60.0):
       """
       Wait for an edge event on a GPIO.
@@ -4435,6 +4867,29 @@ class pi():
       a = _wait_for_edge(self._notify, user_gpio, edge, wait_timeout)
       return a.trigger
 
+   def wait_for_event(self, event, wait_timeout=60.0):
+      """
+      Wait for an event.
+
+             event:= 0-31.
+      wait_timeout:= >=0.0 (default 60.0).
+
+      The function returns when the event is signalled or after
+      the number of seconds specified by timeout has expired.
+
+      The function returns True if the event is detected,
+      otherwise False.
+
+      ...
+      if pi.wait_for_event(23):
+         print("event detected")
+      else:
+         print("wait for event timed out")
+      ...
+      """
+      a = _wait_for_event(self._notify, event, wait_timeout)
+      return a.trigger
+
    def __init__(self,
                 host = os.getenv("PIGPIO_ADDR", ''),
                 port = os.getenv("PIGPIO_PORT", 8888)):
@@ -4511,12 +4966,12 @@ class pi():
 
          s = "Can't connect to pigpio at {}({})".format(str(h), str(port))
 
-         print(except_a.format(s))
+         print(_except_a.format(s))
          if exception == 1:
-             print(except1)
+             print(_except_1)
          else:
-             print(except2)
-         print(except_z)
+             print(_except_2)
+         print(_except_z)
 
    def stop(self):
       """Release pigpio resources.
@@ -4580,6 +5035,18 @@ def xref():
 
    bits = (1<<1) | (1<<7) | (1<<23)
 
+   bsc_control:
+
+   . .
+   22 21 20 19 18 17 16 15 14 13 12 11 10  9  8  7  6  5  4  3  2  1  0
+    a  a  a  a  a  a  a  -  - IT HC TF IR RE TE BK EC ES PL PH I2 SP EN
+   . .
+
+   aaaaaaa defines the I2C slave address (only relevant in I2C mode)
+
+   Bits 0-13 are copied unchanged to the BSC CR register.  See
+   pages 163-165 of the Broadcom peripherals document.
+
    byte_val: 0-255
    A whole number.
 
@@ -4615,9 +5082,12 @@ def xref():
    range_        @ Fully On
 
    edge: 0-2
+
+   . .
    EITHER_EDGE = 2 
    FALLING_EDGE = 1 
    RISING_EDGE = 0
+   . .
 
    errnum: <0
 
@@ -4732,10 +5202,17 @@ def xref():
    PI_FILE_IS_A_DIR = -138
    PI_BAD_SHELL_STATUS = -139
    PI_BAD_SCRIPT_NAME = -140
+   PI_BAD_SPI_BAUD = -141
+   PI_NOT_SPI_GPIO = -142
+   PI_BAD_EVENT_ID = -143 
    . .
 
+   event:0-31
+   An event is a signal used to inform one or more consumers
+   to start an action.
+
    file_mode:
-   The mode may have the following values.
+   The mode may have the following values
 
    . .
    FILE_READ   1
@@ -4743,7 +5220,7 @@ def xref():
    FILE_RW     3
    . .
 
-   The following values can be or'd into the file open mode.
+   The following values can be or'd into the file open mode
 
    . .
    FILE_APPEND 4
@@ -4781,7 +5258,7 @@ def xref():
 
    See [*get_hardware_revision*].
 
-   The user GPIO are marked with an X in the following table.
+   The user GPIO are marked with an X in the following table
 
    . .
              0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15
@@ -4808,8 +5285,13 @@ def xref():
    of a pulse.
 
    handle: >=0
-   A number referencing an object opened by one of [*file_open*],
-   [*i2c_open*], [*notify_open*], [*serial_open*], [*spi_open*].
+   A number referencing an object opened by one of the following
+
+   [*file_open*] 
+   [*i2c_open*] 
+   [*notify_open*] 
+   [*serial_open*] 
+   [*spi_open*]
 
    host:
    The name or IP address of the Pi running the pigpio daemon.
@@ -4831,6 +5313,8 @@ def xref():
    level logic.
 
    level: 0-1 (2)
+
+   . .
    CLEAR = 0 
    HIGH = 1 
    LOW = 0 
@@ -4838,6 +5322,7 @@ def xref():
    ON = 1 
    SET = 1 
    TIMEOUT = 2 # only returned for a watchdog timeout
+   . .
 
    MISO:
    The GPIO used for the MISO signal when bit banging SPI.
@@ -4846,6 +5331,7 @@ def xref():
 
    1.The operational mode of a GPIO, normally INPUT or OUTPUT.
 
+   . .
    ALT0 = 4 
    ALT1 = 5 
    ALT2 = 6 
@@ -4854,13 +5340,16 @@ def xref():
    ALT5 = 2 
    INPUT = 0 
    OUTPUT = 1
+   . .
 
    2. The mode of waveform transmission.
 
+   . .
    WAVE_MODE_ONE_SHOT = 0 
    WAVE_MODE_REPEAT = 1 
    WAVE_MODE_ONE_SHOT_SYNC = 2 
    WAVE_MODE_REPEAT_SYNC = 3
+   . .
 
    MOSI:
    The GPIO used for the MOSI signal when bit banging SPI.
@@ -4892,9 +5381,11 @@ def xref():
    The string to be passed to a [*shell*] script to be executed.
 
    pud: 0-2
+   . .
    PUD_DOWN = 1 
    PUD_OFF = 0 
    PUD_UP = 2 
+   . .
 
    pulse_len: 1-100
    The length of the trigger pulse in microseconds.
@@ -4943,9 +5434,11 @@ def xref():
    seek_from: 0-2
    Direction to seek for [*file_seek*].
 
+   . .
    FROM_START=0 
    FROM_CURRENT=1 
    FROM_END=2 
+   . .
 
    seek_offset:
    The number of bytes to move forward (positive) or backwards
@@ -5003,13 +5496,20 @@ def xref():
    The number of seconds to wait in [*wait_for_edge*] before timing out.
 
    wave_add_*:
-   One of [*wave_add_new*] , [*wave_add_generic*], [*wave_add_serial*].
+   One of the following
+
+   [*wave_add_new*] 
+   [*wave_add_generic*] 
+   [*wave_add_serial*]
 
    wave_id: >=0
    A number referencing a wave created by [*wave_create*].
 
    wave_send_*:
-   One of [*wave_send_once*], [*wave_send_repeat*].
+   One of the following
+
+   [*wave_send_once*] 
+   [*wave_send_repeat*]
 
    wdog_timeout: 0-60000
    Defines a GPIO watchdog timeout in milliseconds.  If no level