Rexx/PFIO
Version 1.0
Copyright (C) 2013 Mark Hessling <mark@rexx.org>

TABLE OF CONTENTS

1. RexxPFIO/Introduction [ Modules ]

[ Top ] [ Modules ]

DESCRIPTION

Rexx/PFIO is an external function package that provides a Rexx interface to the PiFace Digital I/O board; an add-on board to the Raspberry Pi.

USAGE

To make the external functions available add the following lines before: the first call to one of the functions in the package:

Call RxFuncAdd 'PFIO_LoadFuncs', 'rexxpfio', 'PFIO_LoadFuncs'
Call PFIO_LoadFuncs

DERIVED FROM

Rexx/PFIO was generated by RexxPackage from the PiFace C source code; pfio.h

NOTES

The PiFace has 8 input ports and 8 output ports; numbered 1-8 to be consistent with Rexx's philosophy. All other PiFace documentation will base port numbers starting at 0. The first two output ports are linked to the two relays on the board, so if you write a value of 1 to the first two ouput ports, the associated relay will be triggered.

TODO

BUGS

PORTABILITY

INSTALLATION

Rexx/PFIO is distributed as source and as a Debian package. The name of the Debian package will be in the following format:

   rexxpfio-interpreter_rexxpfio-version-1_armhf-Debian-debian-version.deb

Where:

   interpreter will be one of regina, oorexx or rexxtrans

   rexxpfio-version is the version of Rexx/PFIO

   debian-version is the version of Debian Rexx/PFIO was built on

To install the Debian package:

   % sudo dpkg -i package file

To install Rexx/PFIO from source:

   unpack the source

   % ./configure --with-rexx=interpreter

   where interpreter is one of regina, oorexx or rexxtrans

   % make

   % sudo make install

   % sudo ldconfig

SEE ALSO

Rexx/PFIO lives at http://rexxpfio.sf.net

COPYRIGHT

Rexx/PFIO is Copyright(C) 2013-2013 Mark Hessling <mark@rexx.org>

2. RexxPFIO/Constants [ Modules ]

[ Top ] [ Modules ]

DESCRIPTION

The following "constants" are defined when Rexx/PFIO starts. By default, all constants are stored in an array with the stem preset to !REXXPFIO.! This can be changed by using the 'CONSTANTPREFIX' value of PFIO_variable(). If you use "Procedure" on your labels, you MUST "EXPOSE !REXXPFIO." or the stem you set with PFIO_variable() will not be visible. To reference the constants defined below, you must prefix them. So the "constant" HAVE_REXXCALLBACK would be, by default, referenced in your code as !REXXPFIO.!HAVE_REXXCALLBACK.

SEE ALSO

PFIO_variable

2.1. Constants/MiscellaneousFlags [ Definitions ]

[ Top ] [ Constants ] [ Definitions ]

NAME

MiscellaneousFlags

DESCRIPTION

The following is a list of miscellaneous flags. ATTRIBUTES - HAVE_REXXCALLBACK - 1 if the interpreter supports RexxCallback() API - other common constants for package

3. RexxPFIO/Functions [ Modules ]

[ Top ] [ Modules ]

DESCRIPTION

These following functions implement the package functionality.

3.1. Functions/PFIO_deinit [ Functions ]

[ Top ] [ Functions ] [ Functions ]

NAME

PFIO_deinit

SYNOPSIS

rcode = PFIO_deinit()

FUNCTION

Does PiFace cleanup.

ARGUMENTS

None

RESULT

Always returns 0.

SEE ALSO

PFIO_init

SOURCE

...
rcode = PFIO_deinit()

3.2. Functions/PFIO_digital_read [ Functions ]

[ Top ] [ Functions ] [ Functions ]

NAME

PFIO_digital_read

SYNOPSIS

rcode = PFIO_digital_read( port )

FUNCTION

Reads the status of the specified input port.

ARGUMENTS

RESULT

If a circuit is complete on the specified port, 1 is returned otherwise 0 is returned.

SEE ALSO

PFIO_digital_write(), PFIO_read_input()

NOTES

SOURCE

...
rcode = PFIO_digital_read( port )
If rcode = 1 Then Say 'Port' port 'has a complete circuit'
Else Say 'Port' port 'has an incomplete circuit'

3.3. Functions/PFIO_digital_write [ Functions ]

[ Top ] [ Functions ] [ Functions ]

NAME

PFIO_digital_write

SYNOPSIS

Call PFIO_digital_write port, value

FUNCTION

Write a 0 or 1 to the specified output port.

ARGUMENTS

RESULT

None

SEE ALSO

PFIO_digital_read

NOTES

For ports 1 and 2 the associated relays (and their connections) are triggered

SOURCE

...
Call PFIO_digital_write 2, 1

3.4. Functions/PFIO_init [ Functions ]

[ Top ] [ Functions ] [ Functions ]

NAME

PFIO_init

SYNOPSIS

rcode = PFIO_init()

FUNCTION

Determines if a PiFace card is present and initialises the PiFace interface.

ARGUMENTS

None

RESULT

A value less than zero indicates an error, anything else is a successful initialisation.

SEE ALSO

PFIO_deinit

SOURCE

...
If PFIO_init() < 0 Then
   Do
      Say 'Cannot init PiFace'
      Exit 0
   End

3.5. Functions/PFIO_read_input [ Functions ]

[ Top ] [ Functions ] [ Functions ]

NAME

PFIO_read_input

SYNOPSIS

rcode = PFIO_read_input( )

FUNCTION

This function returns the state of all input ports as a number between 0 and 255 inclusive

ARGUMENTS

None

RESULT

The state of all input ports

SEE ALSO

PFIO_digital_read

NOTES

Each bit that is set to 1 in the returned value represents a 1 on the matching input port. Assuming PFIO_read_input returns 6, input ports 2 and 3 are set to 1 and all other ports are set to 0. Ports are numbered 1 through 8.

SOURCE

...
onoff.0 = 'off'
onoff.1 = 'on'
...
rcode = PFIO_read_input()
binary = Reverse( Right( x2b( d2x( rcode ) ), 8, '0' ) )
Do i = 1 To 8
   status = Substr( binary, i, 1 )
   Say 'Status of port' i 'is:' onoff.status
End

3.6. Functions/PFIO_read_output [ Functions ]

[ Top ] [ Functions ] [ Functions ]

NAME

PFIO_read_output

SYNOPSIS

rcode = PFIO_read_output()

FUNCTION

This function returns the state of all output ports as a number between 0 and 255 inclusive

ARGUMENTS

None

RESULT

The state of all output ports

SEE ALSO

PFIO_write_output, PFIO_digital_read

NOTES

Each bit that is set to 1 in the returned value represents a 1 written to the matching port. Assuming PFIO_read_output returns 6, ports 2 and 3 are set to 1 and all other ports are set to 0.

SOURCE

...
Call PFIO_write_output 6
Say 'PFIO_read_output should be 6. It is:' PFIO_read_output()

3.7. Functions/PFIO_write_output [ Functions ]

[ Top ] [ Functions ] [ Functions ]

NAME

PFIO_write_output

SYNOPSIS

Call PFIO_write_output value

FUNCTION

Writes a 0 or 1 to the matching output port based on the input value

ARGUMENTS

RESULT

None

SEE ALSO

PFIO_read_output, PFIO_digital_write

NOTES

All 8 output ports are written to can at the same time with this function. For example Call PFIO_write_output 6 will send a 1 to ports 2 and 3 and a 0 to all other ports.

SOURCE

...
Call PFIO_write_output 6
Say 'PFIO_read_output should be 6. It is:' PFIO_read_output()

4. RexxPFIO/PackageManagement [ Modules ]

[ Top ] [ Modules ]

DESCRIPTION

These functions are common to most Rexx external function packages. They descibe how the behaviour of the package can be changed.

4.1. PackageManagement/PFIO_LoadFuncs [ Functions ]

[ Top ] [ PackageManagement ] [ Functions ]

NAME

PFIO_LoadFuncs

SYNOPSIS

rcode = PFIO_LoadFuncs()

FUNCTION

Loads all other RexxPFIO external functions

ARGUMENTS

None

RESULT

0 in all cases

SEE ALSO

PFIO_DropFuncs

NOTES

4.2. PackageManagement/PFIO_DropFuncs [ Functions ]

[ Top ] [ PackageManagement ] [ Functions ]

NAME

PFIO_DropFuncs

SYNOPSIS

rcode = PFIO_DropFuncs(["UNLOAD"])

FUNCTION

Cleans up RexxPFIO environment and optionally will drop the external functions.

ARGUMENTS

RESULT

0 in all cases

SEE ALSO

PFIO_LoadFuncs

NOTES

4.3. PackageManagement/PFIO_Variable [ Functions ]

[ Top ] [ PackageManagement ] [ Functions ]

NAME

PFIO_Variable

SYNOPSIS

rcode = PFIO_Variable(Variable [,NewValue])

FUNCTION

Get or set an internal RexxPFIO variable.

ARGUMENTS

RESULT

When setting a variable, then 0 if success, any other value is an error When getting a variable, then the value of the variable is returned.

NOTES

The "Variable" argument can be one of:

      DEBUG (settable)
         0 - no debugging
         1 - all Rexx variables set by RexxPFIO are displayed as they are set
         2 - all RexxPFIO functions are traced on entry with argument values and
             on exit with the return value
         4 - all internal RexxPFIO functions are traced with their arguments
             (really only useful for developers)
         The values can be added together for a combination of the above details.
      DEBUGFILE (settable)
         Where any debugging output is written. By default this goes to
         the system's error stream; usually 'stderr'.
      CONSTANTPREFIX (settable)
         The variable name prefix for all RexxPFIO constants. By default this is
         '!REXXPFIO.!'. If you change this, it is useful to make the prefix result
         in stemmed variables; this makes it far easier to EXPOSE these constants.
      VERSION (readonly)
         The full version details of RexxPFIO in the format:
         package version version_date
         Where:
            package      - the string 'rexxpfio'
            version      - package version in n.n format; eg 1.0
            version_date - date package was released in DATE('N') format

SOURCE

...
Say 'We are running at debug level:' PFIO_Variable( 'DEBUG' )

4.4. PackageManagement/PFIO_QueryFunction [ Functions ]

[ Top ] [ PackageManagement ] [ Functions ]

NAME

PFIO_QueryFunction

SYNOPSIS

rcode = PFIO_QueryFunction(FunctionName|ResultArray[, Option])

FUNCTION

Populates an array of all functions supplied by this package depending on Option

ARGUMENTS

RESULT

0 if successful or 1 if the FunctionName is not found

NOTES

To determine if a FunctionName can be executed in your code, pass the function name as the first argument, and 'R' as the second. If the function can be called the function returns 0, otherwise it returns 1