                                     MCPIO
                                     ~~~~~

  ----------------------------------------------------------------------------
     Introduction
     Using MCPIO
     SWIs
     Errors
     Contents (see end of file)
  About this manual
  ============================================================================

                                   About MCPIO
                                   ~~~~~~~~~~~

    MCPIO is a module to control MCP23017 IIC Expander ports.

    Ciseco produce some neat and cheap boards for interfacing to the
    Raspberry Pi using the GPIO header. The SliceOfPI/O board has an MCP23017
    16-Bit I/O Expander chip connected to the Pi's IIC bus. Another board
    using the same chip is the Hobbytronics Expander board, and MCPIO will
    work with this and any other similar boards. Up to 8 Expanders can be
    linked to the IIC bus and MCPIO can address any that are fitted.

    The MCPIO module treats each chip as two 8-bit ports which can have any
    bits configured for input or output. The SliceOfPI/O board, and the
    SliceOfPi, also bring out 8 GPIO pins to a single 8-bit header, which
    MCPIO treats as far as possible in an identical manner to the other ports.

    The ports, labelled A and B on the board, are referred to as 0 and 1; the
    GPIO port, labelled GP, is -1. Before a port is used it should first be
    configured to make its bits input or output using SWI "MCPIO_Direction".
    Then the polarity of the input bits should be configured using SWI
    "MCPIO_Polarity".

    By default all bits are input and low. To make an input bit show logic 1
    it must be connected to a positive voltage. If the polarity is changed to
    high, a pullup resistor in the chip is activated and to make an input bit
    show logic 1 it must be connected to ground.

    The state of the output bits of a port can be set with SWI
    "MCPIO_Output". The current state of all bits of a port can be read with
    SWI "MCPIO_Input".

    The above SWIs can also be used to read the current settings of the
    ports. The GPIO port cannot be read in the same way as the IIC ports, so
    MCPIO keeps a copy of each last setting used. This will work if all
    programs on a machine are using the MCPIO module. However, if another
    module is used to modify GPIO pins, MCPIO will be ignorant of the changes.

    The chips are given and address between 0 and 7 by links on the board.
    MCPIO numbers a port by (address*2+port). Port numbers run from -1 to 15
    if the GPIO port is included. The IIC bus used is 0, which will be so
    whichever revision of Pi is used, because RISC OS accounts for this.

    SWI "MCPIO_Pin" only applies to the GP port. It can be used to set the
    state of a single pin [0-7] and it does this as fast as possible.

    The name of the IO controller, its identifier, the board number and
    revision can be found with SWI "MCPIO_Info".
    --------------------------------------------------------------------------
    MCPIO is a small, specialised module written for the Raspberry Pi and
    generates error &814960,"MCPIO only runs on the Raspberry Pi", if an

                                                                        Page 1
    attempt is made to load it on any other machine. It provides a somewhat
    different API to the generalised GPIO module, which can be used with a
    wide range of options on several different ARM boards.

    The original MCPIO was written for the first Pi boards and was not
    updated for later ones. This version has been updated to work with boards
    upd to the 4B, but there has been no practical testing.
    ==========================================================================

                                 About this manual
                                 ~~~~~~~~~~~~~~~~~

      This manual was written by Steve Drain for MCPIO version 0.30 beta (15
      Jun 2020).

          http://www.kappa.me.uk/
          mailto:steve@kappa.me.uk

      This manual is 0.30 beta (15 Jun 2020).
      ========================================================================

        Symbols
        ~~~~~~~
        Numeric
        ~~~~~~~
        Alphabetic
        ~~~~~~~~~~
          About MCPIO
          About this manual
          Errors
          MCPIO_Direction (&59340)
          MCPIO_Info (&59345)
          MCPIO_Input (&59343)
          MCPIO_Output (&59342)
          MCPIO_Pin (&59344)
          MCPIO_Polarity (&59341)
          Name
          SWIs
          Using MCPIO
        ======================================================================

                                    Using MCPIO
                                    ~~~~~~~~~~~

      The MCPIO module can be replaced while it is active. It is very small
      and is best included within any application that uses it and RMEnsured
      in the !Run file from there, eg:

          RMEnsure MCPIO 0.10 RMLoad MyApp:Modules.MCPIO
      ========================================================================

                                       SWIs
                                       ~~~~

    MCPIO_Direction
    MCPIO_Polarity
    MCPIO_Output
    MCPIO_Input
    MCPIO_Pin
    MCPIO_Info
    ==========================================================================



                                                                        Page 2
                              MCPIO_Direction (&59340)
                              ~~~~~~~~~~~~~~~~~~~~~~~~

      Sets the direction of port bits to output or input.
      ------------------------------------------------------------------------
      <=  R0 = port number: -1 to 15
          R1 = bit mask: only byte0 is significant
      =>  R0 preserved
          R1 current value if r1=-1 on entry, otherwise preserved
      ------------------------------------------------------------------------
         A mask bit value of 0 sets a port bit to output and 1 to input
      ------------------------------------------------------------------------

      ========================================================================

                              MCPIO_Polarity (&59341)
                              ~~~~~~~~~~~~~~~~~~~~~~~

      Sets the polarity of port input bits to low or high.
      ------------------------------------------------------------------------
      <=  R0 = port number: -1 to 15
          R1 = bit mask: only byte0 is significant
      =>  R0 preserved
          R1 current value if r1=-1 on entry, otherwise preserved
      ------------------------------------------------------------------------
         A mask bit value of 0 sets a port bit to low and 1 to high.
         Only input bits are affected.
         A low bit needs to be connected to PWR to be logic 1 and a high bit
          to GND.
      ------------------------------------------------------------------------

      ========================================================================

                               MCPIO_Output (&59342)
                               ~~~~~~~~~~~~~~~~~~~~~

      Sets the level of port output bits to GND or PWR.
      ------------------------------------------------------------------------
      <=  R0 = port number: -1 to 15
          R1 = bit mask: only byte0 is significant
      =>  R0 preserved
          R1 current value if r1=-1 on entry, otherwise preserved
      ------------------------------------------------------------------------
         A mask bit value of 0 sets a port output bit to GND and 1 to PWR.
         Only output bits are affected.
      ------------------------------------------------------------------------

      ========================================================================

                                MCPIO_Input (&59343)
                                ~~~~~~~~~~~~~~~~~~~~

      Reads the level of all port bits.
      ------------------------------------------------------------------------
      <=  R0 = port number: -1 to 15
          R1 = bit mask: only byte0 is significant
      ------------------------------------------------------------------------
         A mask bit value of 0 shows a port bit at logic 0 and 1 at logic 1.
         All bits are read; output bits show the current output state.
      ------------------------------------------------------------------------

      ========================================================================


                                                                        Page 3
                                 MCPIO_Pin (&59344)
                                 ~~~~~~~~~~~~~~~~~~

      Sets the level of a GP pin to GND or PWR.
      ------------------------------------------------------------------------
      <=  R0 = pin number 0 to 7
          R1 = state; 0 off, otherwise on
      =>  R0 corrupted
          R1 corrupted
      ------------------------------------------------------------------------
         Toggling a pin using the BASIC SYS keyword on a standard Pi at
          800MHz can be done at about 250kHz. From machine code this is about
          700kHz
         The pin correspondence for Pi revison 1 is:
          GP   pin number      0  1  2  3  4  5  6  7
          GPIO pin number     17 18 21 22 23 24 25 04
          Revision 2 boards replace GPIO 21 with 27. which MCPIO accounts for.
         Only output bits are affected.
      ------------------------------------------------------------------------

      ========================================================================

                                MCPIO_Info (&59345)
                                ~~~~~~~~~~~~~~~~~~~

      Returns information about the Pi.
      ------------------------------------------------------------------------
      =>  R0 = the board identity word
          R1 = pointer to brief board name
          R2 = revison number
          R3 = size of memory by 256MB
      ------------------------------------------------------------------------

      ------------------------------------------------------------------------


        1A
        1B
        1A+
        1B+
        2B
        3B
        3A+
        3B+
        4B
        Z
        ZW
        CM1
        CM3
      ========================================================================

                                      Errors
                                      ~~~~~~

    &814960  "MCPIO only runs on the Raspberry Pi"

    If an attempt is made address an IIC chip that is not present there will
    be error &131840, "No acknowledge from IIC device".
    ==========================================================================





                                                                        Page 4
                                C o n t e n t s
                                ~~~~~~~~~~~~~~~


                        MCPIO                          1

                        About MCPIO                    1
                          About this manual            2
                              List of all pages        2
                          Using MCPIO                  2

                        SWIs                           2
                          MCPIO_Direction (&59340)     3
                          MCPIO_Polarity (&59341)      3
                          MCPIO_Output (&59342)        3
                          MCPIO_Input (&59343)         3
                          MCPIO_Pin (&59344)           4
                          MCPIO_Info (&59345)          4

                        Errors                         4
































    +----------------------------------------------------------------------+
    |                                                                      |
    | This text file was converted from a StrongHelp manual on 15 Jun 2020 |
    |                                                                      |
    |             using !StHlp2Txt version 1.10 (8 June 2001)              |
    |                           by Chris Morison                           |
    |                                                                      |
    |               email: organizer@morison.net                           |
    |                 web: http://www.organizer.morison.net/               |
    |                                                                      |
    +----------------------------------------------------------------------+

                                                                        Page 5
