Library for AdvaBoard RPi1 - Python binding

Version: 2014-06-26
Status: beta
SeeAlso:AdvaBoard RPi1 documentation, am_rpi_advaboard.c/.h, rpi.py
Note:If you want to access the AdvaBoard RPi1, better only use the functions in this library and do not access the Raspberry Pi directly.
Author: Advamation, Roland Koebler (support@advamation.de)
Copyright: (c) Advamation (info@advamation.de)
License:open-source / MIT
RCS:advaboard.py,v 1.14 2014/06/26 13:00:37 rk Exp

Table of contents

1   generic usage

Before using the library, the Python module has to be imported, e.g.:

from am_rpi import advaboard
from am_rpi.advaboard import AM_ERROR, AM_ERROR_CODE

# optionally:
from am_rpi.advaboard import GPIO, RTC_STATUS, RTC_CONTROL, IO_CONFIG, ANALOG_CONTROL, SPI_CLKCFG, SPI_CLK, I2C_CLK
from am_rpi.advamation import AM_CMD, AM_LOG_LEVEL
from am_rpi import advamation

The functions usually throw AM_ERROR on error, so always catch it, e.g.:

try:
    advaboard.init()
except AM_ERROR as err:
    print("Error: AdvaBoard RPi1-init failed. (%s / %d)" % (err.message, err.code))
    sys.exit(1)

try:
    info = advaboard.info()
    advaboard.led(0x02)
    ...
except AM_ERROR as err:
    print("Exception: %s (%d)" % (err.message, err.code))
    sys.exit(1)

advaboard.exit()

In addition, they throw LibraryNotInitialized if some functions are called before initializing the library, and e.g. TypeError for invalid parameters.

Many functions return several bytes as a bytestring.

  • In Python 3, these bytestrings can be accesses somehow like a list of integers (i.e. if you access a bytestring-element (e.g. s[0]), you'll get the integer-value of the byte).
  • In Python 2, accessing a bytestring-element gives you a 1-character-string. To get the integer-value, you have to use ord() for every element, or use the function advamation.bytes2list().

Some example-programs can be found in the example-directory.

2   init / exit / logging

2.1   Init library, Raspberry Pi and AdvaBoard RPi1.

Init the library, check and init the Raspberry Pi, GPIO pins, I2C, SPI and AdvaBoard RPi1.

Does nothing (except incrementing the init-counter) if it already has been called before. init() and exit() must always be called pairwise.

Usage:init()
Raises:AM_ERROR

2.2   Exit library.

De-initialize the library. Must be used for every successful call of init().

Usage:exit()

2.3   Configure logging.

All messages up to "level" are printed and/or stored in the logfile. DEBUG/INFO are printed to stdout, MESSAGE/WARNING/CRITICAL/ERROR are printed to stderr.

The available levels are:

  • AM_LOG_LEVEL.DEBUG
  • AM_LOG_LEVEL.INFO
  • AM_LOG_LEVEL.MESSAGE
  • AM_LOG_LEVEL.WARNING (default)
  • AM_LOG_LEVEL.CRITICAL
  • AM_LOG_LEVEL.ERROR
Usage:

logging(level=AM_LOG_LEVEL.WARNING, logfile=None, logfile_level=AM_LOG_LEVEL.WARNING)
Parameters:
  • level: log-level for "print"
  • logfile_level: log-level for the logfile
  • logfile: filename of the logfile (None: no logfile)
Raises:

AM_ERROR (AM_ERROR_CODE: INVALID_ARGUMENT, IO if the logfile cannot be opened (see errno for details))
SeeAlso:

advamation.AM_LOG_LEVEL

3   basic / low-level access to the AdvaBoard RPi1

Basic functions to access the AdvaBoard RPi1.

These functions can be used to access all functions of the AdvaBoard RPi1. But they are rather low-level, so better look at the higher-level-functions in the next sections.

SeeAlso:AdvaBoard RPi1 documentation

3.1   F912: Communicate with AdvaBoard RPi1 - F912 microcontroller.

Communicate with the SiLabs C8051F912-microcontroller (power-controller) of the AdvaBoard RPi1 (incl. locking).

Usage:

f912_comm(cmd, txdata=None)
Parameters:
  • cmd: Advamation-I2C-protocol-command (AM_CMD.*)
  • txdata: transmit-data (bytestring or list of 0..0xFF, 0..16 bytes)
Returns:

received data (bytestring)
Raises:

AM_ERROR, LibraryNotInitialized
SeeAlso:

advamation.AM_CMD, AdvaBoard RPi1 documentation, Advamation RS485-/I2C-protocol, advamation.py, am_rpi.i2c_prot()

3.2   F912: Check command-status.

Check if the commands, sent to the SiLabs C8051F912-microcontroller (power-controller) of the AdvaBoard RPi1, were completely processed.

Usage:f912_cmdstatus()
Returns:command-status (0: done, >0: busy)
Raises:AM_ERROR, LibraryNotInitialized
Note:This is only supported if the AdvaBoard RPi1-firmware is >= 20140219. For older firmware, AM_ERROR_CODE.NOT_IMPLEMENTED is raised.
SeeAlso:AdvaBoard RPi1 documentation, Advamation RS485-/I2C-protocol

3.3   F912: Manually lock AdvaBoard RPi1 - F912 microcontroller.

Manually lock the SiLabs C8051F912-microcontroller (power-controller) of the AdvaBoard RPi1 for several communications.

Note that you additionally have to use a mutex, if you're accessing I2C from several threads in the same program.

Usage:

f912_lock(timeout_ms=-1)
Parameters:
  • timeout_ms: timeout in ms (0..65535), 0=non-blocking, -1/omitted=use auto-locking-timeout
Raises:

AM_ERROR (AM_ERROR_CODE: BUSY after timeout), LibraryNotInitialized

3.4   F912: Manually unlock AdvaBoard RPi1 - F912 microcontroller.

Unlock the F912 again after f912_lock(). This has to be used for every successful call to f912_lock().

Usage:f912_unlock()
Raises:LibraryNotInitialized

3.5   F912: Set auto-locking-timeout.

Set timeout, after which F912-communication-functions raise AM_ERROR(AM_ERROR_CODE.BUSY) if they cannot lock the F912.

Usage:

f912_locking_timeout(timeout_ms)
Parameters:
  • timeout_ms: timeout in ms (0..65535, default: 1000ms)
Raises:

LibraryNotInitialized

3.6   F353: Communicate with AdvaBoard RPi1 - F353 microcontroller.

Communicate with the SiLabs C8051F353-microcontroller (I/O-controller) of the AdvaBoard RPi1 (incl. locking).

Usage:

f353_comm(cmd, txdata=None)
Parameters:
  • cmd: Advamation-I2C-protocol-command (AM_CMD.*)
  • txdata: transmit-data (bytestring or list of 0..0xFF, 0..16 bytes)
Returns:

received data (bytestring)
Raises:

AM_ERROR, LibraryNotInitialized
SeeAlso:

advamation.AM_CMD, AdvaBoard RPi1 documentation, Advamation RS485-/I2C-protocol, advamation.py, am_rpi.i2c_prot()

3.7   F353: Check command-status.

Check if the commands, sent to the SiLabs C8051F353-microcontroller (I/O-controller) of the AdvaBoard RPi1, were completely processed.

Usage:f353_cmdstatus()
Returns:command-status (0: done, >0: busy)
Raises:AM_ERROR, LibraryNotInitialized
Note:This is only supported if the AdvaBoard RPi1-firmware is >= 20140219. For older firmware, AM_ERROR_CODE.NOT_IMPLEMENTED is raised.
SeeAlso:AdvaBoard RPi1 documentation, Advamation RS485-/I2C-protocol

3.8   F353: Manually lock AdvaBoard RPi1 - F353 microcontroller.

Manually lock the SiLabs C8051F353-microcontroller (I/O-controller) of the AdvaBoard RPi1 for several communications.

Note that you additionally have to use a mutex, if you're accessing I2C from several threads in the same program.

Usage:

f353_lock(timeout_ms=-1)
Parameters:
  • timeout_ms: timeout in ms (0..65535), 0=non-blocking, -1/omitted=use auto-locking-timeout
Raises:

AM_ERROR (AM_ERROR_CODE: BUSY after timeout), LibraryNotInitialized

3.9   F353: Manually unlock AdvaBoard RPi1 - F353 microcontroller

Unlock the F353 again after f353_lock(). This has to be used for every successful call to f353_lock().

Usage:f353_unlock()
Raises:LibraryNotInitialized

3.10   F353: Set auto-locking-timeout.

Set timeout, after which F353-communication-functions raise AM_ERROR(AM_ERROR_CODE.BUSY) if they cannot lock the F353.

Usage:

f353_locking_timeout(timeout_ms)
Parameters:
  • timeout_ms: timeout in ms (0..65535. default: 1000ms)
Raises:

LibraryNotInitialized

3.11   CPLD: Communicate with AdvaBoard RPi1 - CPLD.

Write/read registers of the Xilinx CPLD of the AdvaBoard RPi1.

Usage:

cpldreg(tx)
Parameters:
  • tx: byte to send (bytestring or list of 0..0xFF, 1 byte)
Returns:

recevied byte (bytestring)
Raises:

AM_ERROR, LibraryNotInitialized
SeeAlso:

AdvaBoard RPi1 documentation, am_rpi.spi_comm()

3.12   GPIOs: Write Raspberry Pi GPIOs.

Set/clear Raspberry Pi GPIOs, which are connected to the AdvaBoard RPi1.

Valid GPIOs:

  • GPIO.RPi_SEL0
  • GPIO.RPi_SEL1
  • GPIO.RPi_SEL2
  • GPIO.RPi_SEL3
  • GPIO.RPi_PWM
  • GPIO.LCD_RS
Usage:

gpio_write(gpios, level)
Parameters:
  • gpios: GPIOs to write
  • level: 0/False to clear, 1/True to set
Raises:

AM_ERROR (AM_ERROR_CODE: INVALID_ARGUMENT), LibraryNotInitialized
SeeAlso:

GPIO, AdvaBoard RPi1 documentation

3.13   GPIOs: Read Raspberry Pi GPIOs.

Read Raspberry Pi GPIOs, which are connected to the AdvaBoard RPi1.

Usual GPIOs:

  • GPIO.I2C_INT
  • GPIO.TP_INT
  • GPIO.RPi_PWM
  • GPIO.RPi_SEL0
  • GPIO.RPi_SEL1
  • GPIO.RPi_SEL2
  • GPIO.RPi_SEL3
  • GPIO.SPI_MISO
Usage:

gpio_read(gpios=0xffffffff)
Parameters:
  • gpios: GPIOs to read, 0xffffffff for all
Returns:

current input levels, masked by gpios
Raises:

LibraryNotInitialized
SeeAlso:

GPIO, AdvaBoard RPi1 documentation

3.14   SPI: Set the SPI-clock.

Usage:

spi_clk(clkdiv)
Parameters:
  • clkdiv: SPI-clock-divisor (SPI_CLK.* or 4/6/8/10/.../65536)
Raises:

AM_ERROR (AM_ERROR_CODE: INVALID_ARGUMENT), LibraryNotInitialized
Note:

SPI-speed is 250 MHz / clkdiv
SeeAlso:

SPI_CLK, rpi.spi_clk()

3.15   SPI: Set the SPI-clock-phase and -polarity.

The possible clock-phases and -polarities are:

  • SPI_CLKCFG.IDLELOW_SHIFTFALLING_READRISING
  • SPI_CLKCFG.IDLELOW_SHIFTRISING_READFALLING
  • SPI_CLKCFG.IDLEHIGH_SHIFTRISING_READFALLING (default)
  • SPI_CLKCFG.IDLEHIGH_SHIFTFALLING_READRISING
Usage:

spi_clkcfg(clkcfg)
Parameters:
  • clkcfg: clock-phase/-polarity (-1=don't change)
Raises:

AM_ERROR (AM_ERROR_CODE: AM_ERROR_INVALID_ARGUMENT), LibraryNotInitialized
SeeAlso:

SPI_CLK, rpi.spi_config()

3.16   SPI: Set SPI-MUX.

Set SPI-multiplexer of the AdvaBoard RPi1 (without locking!).

Usage:

spi_mux(mux)
Parameters:
  • mux: 0=E-SPI, 1=TFT, 2=TP, 3=SD, -1=don't change
Raises:

AM_ERROR, LibraryNotInitialized

3.17   SPI: Communicate.

This is a low-level-function. If you want to communicate with E-SPI-devices, which are connected to the AdvaBoard RPi1, use am_rpi_advaboard_espi() instead.

Usage:

spi_comm(txdata)
Parameters:
  • txdata: transmit-data (bytestring or list of 0..0xFF)
Returns:

received data (bytestring)
Raises:

AM_ERROR (AM_ERROR_CODE: INVALID_ARGUMENT), LibraryNotInitialized
SeeAlso:

rpi.spi_comm()

3.18   SPI: Manually lock.

Manually lock SPI for several subsequent communications.

Note that you additionally have to use a mutex, if you're accessing the SPI from several threads in the same program.

Usage:

spi_lock(timeout_ms=-1)
Parameters:
  • timeout_ms: timeout in ms (0..65535), 0=non-blocking, -1/omitted=use auto-locking-timeout
Raises:

AM_ERROR (AM_ERROR_CODE: BUSY after timeout), LibraryNotInitialized
SeeAlso:

rpi.spi_lock()

3.19   SPI: Manually unlock.

Unlock SPI again after spi_lock(). This has to be used for every successful call to spi_lock().

Usage:spi_unlock()
Raises:LibraryNotInitialized
SeeAlso:rpi.spi_unlock()

3.20   SPI: Set auto-locking-timeout.

Set timeout, after which SPI-communication-functions raise AM_ERROR(AM_ERROR_CODE.BUSY) if they cannot lock the SPI.

Usage:

spi_locking_timeout(timeout_ms)
Parameters:
  • timeout_ms: timeout in ms (0..65535, default: 1000ms)
Raises:

LibraryNotInitialized
SeeAlso:

rpi.spi_locking_timeout()

3.21   I2C: Communicate.

This is a low-level-function. If you want to communicate with I2C-devices, which are connected to the AdvaBoard RPi1, use i2c() instead.

Usage:

rpii2c_comm(address, txdata=b'', rxlen=0)
Parameters:
  • address: 7-bit I2C-slave address
  • txdata: transmit-data (bytestring or list of 0..0xFF, max. 65535 bytes)
  • rxlen: number of bytes to read (max. 65535)
Returns:

received data (bytestring)
Raises:

AM_ERROR, LibraryNotInitialized
SeeAlso:

rpi.i2c_write_read()

3.22   I2C: Set the I2C-clock.

Usage:

rpii2c_clk(clkdiv)
Parameters:
  • clkdiv: I2C-clock-divisor (I2C_CLK.CLK...kHz or 4/6/8/.../65536)
Raises:

AM_ERROR (AM_ERROR_CODE: INVALID_ARGUMENT), LibraryNotInitialized
Note:

The I2C core clock is 250 MHz; default-clkdiv is 1500 (166.7kHz). (The Raspberry Pi datasheet is wrong, here.)
SeeAlso:

I2C_CLK, rpi.i2c_clk()

3.23   I2C: Manually lock.

Manually lock I2C for several communications.

Note that you additionally have to use a mutex, if you're accessing the I2C from several threads in the same program.

Usage:

rpii2c_lock(timeout_ms=-1)
Parameters:
  • timeout_ms: timeout in ms (0..65535), 0=non-blocking, -1/omitted=use auto-locking-timeout
Raises:

AM_ERROR (AM_ERROR_CODE: AM_ERROR_BUSY after timeout), LibraryNotInitialized
SeeAlso:

rpi.i2c_lock()

3.24   I2C: Manually unlock.

Unlock I2C again after rpii2c_lock(). This must be used for every successful call to rpii2c_lock().

Usage:rpii2c_unlock()
Raises:LibraryNotInitialized
SeeAlso:rpi.i2c_unlock()

3.25   I2C: Set auto-locking-timeout.

Set timeout, after which I2C-communication-functions raise AM_ERROR(AM_ERROR_CODE.BUSY) if they cannot lock the I2C.

Usage:

rpii2c_locking_timeout(timeout_ms)
Parameters:
  • timeout_ms: timeout in ms (0..65535, default: 1000ms)
Raises:

LibraryNotInitialized
SeeAlso:

rpi.i2c_locking_timeout()

4   AdvaBoard RPi1 functions

All AdvaBoard-functionality can be accessed with the "basic/low-level" functions above. But the following functions simplify the use of the most commonly used functionality of the AdvaBoard RPi1.

4.1   system information

4.1.1   Hardware/firmware information.

Retrieve hardware-information from the AdvaBoard RPi1.

Usage:

info()
Returns:

{"model": "...", "rev": "...", "serno": ..., "f912_firmware": "...", "f353_firmware": "...", "cpld_firmware": ...}

  • model: hardware-model ("AdvaBoard RPi1")
  • rev: hardware-revision, e.g. "1"
  • serno: serial-number in BCD, 10 digits/5 bytes
  • f912_firmware: firmware-version of F912-microcontroller
  • f353_firmware: firmware-version of F353-microcontroller
  • cpld_firmware: CPLD-firmware-version (number)
Raises:

AM_ERROR, LibraryNotInitialized

4.1.2   Read temperatures.

Read the temperature-sensors of the microcontrollers on the AdvaBoard RPi1. Note that the returned temperatures are uncalibrated. For more precise measurements, an offset should be calibrated and added to the value.

Usage:

temperature_read()
Returns:

[t_f912, t_f353]`

  • t_f912: temperature of the F912
  • t_f353: temperature of the F353
Raises:

AM_ERROR, LibraryNotInitialized

4.1.3   Get information about the installed AdvaBoard RPi1-software.

Convenience-function, e.g. for RPC. This even works without init().

Usage:info_sw()
Returns:{"installed": True/False, "version": ..., "directory": ...}

4.2   Status

Much of the AdvaBoard RPi1-functionality is implemented by the two microcontrollers on the AdvaBoard. The Raspberry Pi communicates with these microcontrollers via I2C, and sends commands to them, which the microcontrollers then process. Although the microcontrollers are quite fast, they need some time (usually up to a few ms) to process these commands.

For cases where it is necessary that a command is done before the next is sent (e.g. if you configure an I/O as input and then read it, you want to be sure that the input-configuration has finished before reading the I/O), it's possible to check, if the microcontrollers have finished processing the command.

4.2.1   Check if a command is done.

Check if a command is done, e.g. if sent output-values have reached the (hardware-)pins, if a changed I/O-configuration is active or if a manually triggered event completeted.

cmd may be one, or multiple or-combined values of:

  • DONE.POWER
  • DONE.PINS
  • DONE.RTC
  • DONE.IO_DIGITAL
  • DONE.IO_ANALOG
  • DONE.IO_PWM (alias for IO_ANALOG)
  • DONE.EVENTPWR
  • DONE.EVENTIO
  • DONE.I2CCLKEXT
  • DONE.RS485CFG
  • DONE.LED
Usage:

done(cmd)
Parameters:
  • cmd: commands to check
Returns:

True if done, False if not yet done
Raises:

AM_ERROR, LibraryNotInitialized
Note:

This is only supported if the AdvaBoard RPi1-firmware is >= 20140219. For older firmware, AM_ERROR_CODE.NOT_IMPLEMENTED is raised.

4.3   Power-Management

4.3.1   Read voltages.

Read the power-supply-voltages of the AdvaBoard RPi1. Note that this may return arbitrary voltages for unconnected/floating pins (e.g. vbatt is only valid if a battery is connected).

Usage:

voltages_read()
Returns:

{"v5v": ..., "vbatt": ..., "vdd_f912": ...}

  • v5v: voltage of the power-supply
  • vbatt: voltage of the connected battery
  • vdd_f912: internal supply-voltage of the F912
Raises:

AM_ERROR, LibraryNotInitialized

4.3.2   Power-on/off.

Switch power on/off of different parts of the AdvaBoard RPi1. Power-off also disables the CPLD-pins to the appropriate part.

Usage:

power(pwron=-1, cpld_3v=-1, peripheral_5v=-1, rpi=-1, tft=-1, tft_backlight=-1)
Parameters:
  • pwron: 5V-power-supply power-on/off
  • cpld_3v: CPLD and peripheral 3.3V (CPLD-I/O, RS-232-3.3V, Flash)
  • peripheral_5v: peripheral 5.0V (RS-485, E-SPI, RS-232-5V)
  • rpi: Raspberry Pi
  • tft: TFT-display incl. backlight of 4.3"/5.0"
  • tft_backlight: TFT-backlight of 2.4"/3.2"/7.0"
Raises:

AM_ERROR, LibraryNotInitialized
Note:
  • 0=off, 1=on, <0=don't change
  • cpld_3v must be on if peripheral_5v/rpi/tft/tft_backlight is on
  • tft must be on if tft_backlight is on
SeeAlso:

event-based automation below

4.3.3   Power-on/off: Read power-switches.

Read the power-state.

Usage:

power_read()
Returns:

{"pwron": ..., "cpld_3v": ..., "peripheral_5v": ..., "rpi": ..., "tft": ..., "tft_backlight": ...}

True=on, False=off

  • pwron: 5V-power-supply power-on/off
  • cpld_3v: CPLD and peripheral 3.3V (CPLD-I/O, RS-232-3.3V, Flash)
  • peripheral_5v: peripheral 5V (RS-485, E-SPI, RS-232-5V)
  • rpi: Raspberry Pi
  • tft: TFT-display incl. backlight of 4.3"/5.0"
  • tft_backlight: TFT-backlight of 2.4"/3.2"/7.0"
Raises:

AM_ERROR, LibraryNotInitialized

4.3.4   CPLD-pins: Enable/disable.

Enable/disable the CPLD-pins to E-SPI, the Raspberry Pi and TFT-display.

They must be disabled if the appropriate part is powered-off, and must be enabled to access them when they are powered-on.

Usage:

pins(espi_rs485=-1, rpi=-1, tft=-1)
Parameters:
  • espi_rs485: pins to E-SPI and RS-485 (0=disable, 1=enable, -1=don't change)
  • rpi: pins to the Raspberry Pi (0=disable, 1=enable, -1=don't change)
  • tft: pins to the TFT-display (0=disable, 1=enable, -1=don't change)
Raises:

AM_ERROR, LibraryNotInitialized

4.3.5   CPLD-pins: Read enabled/disabled.

Read the enabled-state of the CPLD-pins to E-SPI, the Raspberry Pi and the TFT-Display.

Usage:

pins_read()
Returns:

{"espi_rs485": ..., "rpi": ..., "tft": ...}

  • espi_rs485: E-SPI/RS-485-pins-enabled-status (True/False)
  • rpi: Raspberry Pi-pins-enabled-status (True/False)
  • tft: TFT-display-pins-enabled-status (True/False)
Raises:

AM_ERROR, LibraryNotInitialized

4.3.6   TFT-backlight: Write PWM.

Set PWM for tft_backlight. This modifies the brightness of the backlight of the 3.2" TFT-display, and should be 0xFF for other displays.

Usage:

power_tftblpwm(pwm=0xFF)
Parameters:
  • pwm: PWM-value 0..255
Raises:

AM_ERROR, LibraryNotInitialized

4.3.7   TFT-backlight: Read PWM.

Read PWM of tft_backlight.

Usage:power_tftblpwm_read()
Returns:PWM-value (0..255)
Raises:AM_ERROR, LibraryNotInitialized

4.4   RTC

The initial time of the RTC (in seconds) is 0x10000000 (268435456).

It's also possible to set the RTC to smaller values but this should not be done if alarms are used, since alarms < 0x10000000 are interpreted as relative to the current time, and then relative_alarm + current_time would still be < 0x10000000 and be interpreted as relative alarm, again.

The time is usually interpreted as seconds since the epoch (01.01.1970).

4.4.1   Read RTC-status.

Read the status of the real-time-clock.

bit description values
0 (reserved)  
1 running 0=stopped, 1=running
2 (reserved)  
3 error-flag 0=ok, 1=RTC oscillator failure
4 alarm0-enabled 0=alarm0 disabled, 1=alarm0 enabled
5 alarm0-flag 0=no alarm, 1=alarm0 occurred
6 alarm1-enabled 0=alarm1 disabled, 1=alarm1 enabled
7 alarm1-flag 0=no alarm, 1=alarm1 occurred
Usage:rtc_status()
Returns:RTC-status
Raises:AM_ERROR, LibraryNotInitialized
SeeAlso:RTC_STATUS, AdvaBoard RPi1 documentation

4.4.2   Control the RTC.

control may be one, or multiple or-combined values of:

  • RTC_CONTROL.STOP
  • RTC_CONTROL.START
  • RTC_CONTROL.SET
  • RTC_CONTROL.CLRFLAGS
  • RTC_CONTROL.ALARM0_OFF
  • RTC_CONTROL.ALARM0_ON
  • RTC_CONTROL.ALARM1_OFF
  • RTC_CONTROL.ALARM1_ON
Usage:

rtc_control(control)
Parameters:
  • control: one or more control-bits
Raises:

AM_ERROR, LibraryNotInitialized
SeeAlso:

RTC_CONTROL, AdvaBoard RPi1 documentation

4.4.3   Read the current RTC-time.

Usage:

rtc_read()
Returns:

[time, subseconds]

  • time: current time of the RTC in 32-bit seconds
  • subseconds: 16-bit subseconds
Raises:

AM_ERROR, LibraryNotInitialized

4.4.4   Write RTC-time.

Write time to a RTC register, but do not yet activate it. Use RTC_CONTROL.SET to actually set the RTC to the written time (or use rtc_set()).

The initial time (at power-on) is 0x10000000. Do not set smaller times if you're using alarms.

Usage:

rtc_write(time)
Parameters:
  • time: time in 32-bit seconds
Raises:

AM_ERROR, LibraryNotInitialized

4.4.5   Set RTC-time.

Set RTC (=write time to RTC-register and use RTC_CONTROL.SET).

The initial time (at power-on) is 0x10000000. Do not set smaller times if you're using alarms.

Usage:

rtc_set(time)
Parameters:
  • time: time in 32-bit seconds
Raises:

AM_ERROR, LibraryNotInitialized

4.5   I/O

4.5.1   I/O-configuration: Configure digital-I/Os 0.4..0.7.

Configure the digital-I/Os 0.4..0.7 of the AdvaBoard RPi1. These pins have a weak pullup.

Possible configurations:

  • IO_CONFIG.INPUT: use as input
  • IO_CONFIG.OUTPUT_OPENDRAIN / IO_CONFIG.AM_OUTPUT: use as opendrain-output
  • IO_CONFIG.OUTPUT_PUSHPULL: use as push-pull-output
Usage:

io0_config(io4_ida0, io5_ida1, io6_pwm0, io7_pwm1)
Parameters:
  • io4_ida0: configuration for I/O 4 / IDA0
  • io5_ida1: configuration for I/O 5 / IDA1
  • io6_pwm0: configuration for I/O 6 / PWM0
  • io7_pwm1: configuration for I/O 7 / PWM1
Raises:

AM_ERROR, LibraryNotInitialized
SeeAlso:

IO_CONFIG, analog_control() for IDA, pwm_* for PWM

4.5.2   I/O-configuration: Read configuration of digital-I/Os 0.4..0.7.

Usage:

io0_config_read()
Returns:

[io4_ida0, io5_ida5, io6_pwm0, io7_pwm1]

  • io4_ida0: configuration for I/O 4 / IDA1
  • io5_ida1: configuration for I/O 5 / IDA1
  • io6_pwm0: configuration for I/O 6 / PWM0
  • io7_pwm1: configuration for I/O 7 / PWM1
Raises:

AM_ERROR, LibraryNotInitialized
SeeAlso:

IO_CONFIG

4.5.3   I/O-configuration: Configure digital-I/Os 1.0..1.7.

Configure the digital-I/Os 1.0..1.7 / CPLD-I/O 0..7 of the AdvaBoard RPi1. The CPLD-inputs are special: They don't have a pullup/pulldown, but they keep their current level (low or high) until a different level is applied.

Possible configurations:

  • IO_CONFIG.INPUT: use as input
  • IO_CONFIG.OUTPUT: use as output
Usage:

io1_config(cpldio0, cpldio1, cpldio2, cpldio3, cpldio4, cpldio5, cpldio6, cpldio7)
Parameters:
  • cpldio0..7: configuration for I/O 1.0..1.7 / CPLD-I/O 0..7
Raises:

AM_ERROR, LibraryNotInitialized
Note:

I/O 1.0 is special, since it can also be used as RPi-PWM-output. So, if I/O 1.0 is configured as output, the effective output-level is I/O_1.0_value AND RPi_PWM.

RPi_PWM is set to high at initialization (so I/O 1.0 works as normal I/O), and can be set by advaboard.gpio_write(ADVABOARD_RPi_PWM, level) or by configuring the Raspberry Pi-PWM on P1-12 of the Raspberry Pi.
SeeAlso:

IO_CONFIG

4.5.4   I/O-configuration: Read configuration of digital-I/Os 1.0..1.7.

Usage:

io1_config_read()
Returns:

[cpldio0, cpldio1, cpldio2, cpldio3, cpldio4, cpldio5, cpldio6, cpldio7]

  • cpldio0..7: configuration for I/O 1.0..1.7 / CPLD-I/O 0..7
Raises:

AM_ERROR, LibraryNotInitialized
SeeAlso:

IO_CONFIG

4.5.5   Digital-I/O: Read status.

Read the status of the digital-I/Os of the AdvaBoard RPi1.

byte bit description values
0 0 CPLD-input-update 0=update disabled, 1=update enabled
0 4 event0 enabled 0=disabled, 1=enabled
0 5 event1 enabled 0=disabled, 1=enabled
0 6 event2 enabled 0=disabled, 1=enabled
0 7 event3 enabled 0=disabled, 1=enabled
Usage:io_status()
Returns:status (0..0xFF)
Raises:AM_ERROR, LibraryNotInitialized
SeeAlso:AdvaBoard RPi1 documentation

4.5.6   Digital-I/O: Control digital-I/Os / events.

control may be one, or multiple or-combined values of:

  • IO_CONTROL.CPLDINUPDATE_DISABLE
  • IO_CONTROL.CPLDINUPDATE_ENABLE
  • IO_CONTROL.EVENT0_DISABLE
  • IO_CONTROL.EVENT0_ENABLE
  • IO_CONTROL.EVENT1_DISABLE
  • IO_CONTROL.EVENT1_ENABLE
  • IO_CONTROL.EVENT2_DISABLE
  • IO_CONTROL.EVENT2_ENABLE
  • IO_CONTROL.EVENT3_DISABLE
  • IO_CONTROL.EVENT3_ENABLE
Usage:

io_control(control)
Parameters:
  • control: one or more control-bits
Raises:

AM_ERROR, LibraryNotInitialized
SeeAlso:

IO_CONTROL, AdvaBoard RPi1 documentation

4.5.7   Digital-I/O: Write outputs.

Write digital-outputs.

Usage:

io_write(io7654=-1, cpldio=-1)
Parameters:
  • io7654: values for I/O 0.7..0.4 (0..0xFF, or -1=don't change)
  • cpldio: values for I/O 1.7..1.0 (0..0xFF, or -1=don't change)
Raises:

AM_ERROR, LibraryNotInitialized
Note:
  • io7654: bit 7 is used for I/O 0.7, bit 6 for I/O 0.6 etc.
  • cpldio: bit 7 is used for I/O 1.7, bit 6 for I/O 1.6 etc.
  • For the digital-I/Os which are currently configured as input, only the output-buffers are set; the levels are assigned to these pins, as soon as they are configured as output.

4.5.8   Digital-I/O: Read I/Os 0.4..0.7.

Read digital-I/Os 0.4..0.7 of the AdvaBoard RPi1.

Usage:io_read1()
Returns:digital-I/O-values (0..0xFF)
Raises:AM_ERROR, LibraryNotInitialized
Note:I/O 0.4 uses bit 4 of iovalues, I/O 0.5 uses bit 5, I/O 0.6 uses bit 6, I/O 7 uses bit 7

4.5.9   Digital-I/O: Read all I/Os.

Read all digital-I/Os of the AdvaBoard RPi1.

Usage:io_read2()
Returns:[iovalue0, iovalue1], each 0.0xFF
Raises:AM_ERROR, LibraryNotInitialized
Note:I/O 0.4..0.7 use bit 4..7 of the 1st byte, I/O 1.0..1.7 use bit 0..7 of the 2nd byte

4.5.10   Digital-I/O: Set an output-pin to high.

Set an digital-output (-> high).

Usage:

io_set(i)
Parameters:
  • i: I/O-number, 0x04..0x07 for I/Os 0.4..0.7, 0x10..0x17 I/Os 1.0..1.7
Raises:

AM_ERROR, LibraryNotInitialized
Note:

If the digital-I/O is currently configured as input, only the output-buffer is set; the level is assigned to the pin, as soon as the pin is configured as output.

4.5.11   Digital-I/O: Clear an output-pin to low.

Clear a digital-output (-> low).

Usage:

io_clr(i)
Parameters:
  • i: I/O-number, 0x04..0x07 for I/Os 0.4..0.7, 0x10..0x17 I/Os 1.0..1.7
Raises:

AM_ERROR, LibraryNotInitialized
Note:

If the digital-I/O is currently configured as input, only the output-buffer is set; the level is assigned to the pin, as soon as the pin is configured as output.

4.5.12   Digital-I/O: Get level of an I/O-pin.

Read the level of a digital-I/O-pin.

Usage:

io_get(i)
Parameters:
  • i: I/O-number, 0x04..0x07 for I/Os 0.4..0.7, 0x10..0x17 I/Os 1.0..1.7
Returns:

1 if high, 0 if low
Raises:

AM_ERROR, LibraryNotInitialized

4.5.13   Analog-I/O: Read status.

Read the status of the analog-I/Os of the AdvaBoard RPi1.

byte bit description values
0 0 ADC0 sampling 0=idle, 1=currently sampling
0 1 ADC0 mode 0=oneshot-mode, 1=continuous mode
0 2 ADC0 valid 0=value invalid, 1=value valid
0 3 ADC0 error 0=no error, 1=overflow/underflow occurred
0 4 ADC1 sampling 0=idle, 1=currently sampling
0 5 ADC1 mode 0=oneshot-mode, 1=continuous mode
0 6 ADC1 valid 0=value invalid, 1=value valid
0 7 ADC1 error 0=no error, 1=overflow/underflow occurred
1 0 ADC2 sampling 0=idle, 1=currently sampling
1 1 ADC2 mode 0=oneshot-mode, 1=continuous mode
1 2 ADC2 valid 0=value invalid, 1=value valid
1 3 ADC2 error 0=no error, 1=overflow/underflow occurred
1 4 ADC3 sampling 0=idle, 1=currently sampling
1 5 ADC3 mode 0=oneshot-mode, 1=continuous mode
1 6 ADC3 valid 0=value invalid, 1=value valid
1 7 ADC3 error 0=no error, 1=overflow/underflow occurred
2 0 TEMP sampling 0=idle, 1=currently sampling
2 1 TEMP mode 0=oneshot-mode, 1=continuous mode
2 2 TEMP valid 0=value invalid, 1=value valid
2 3 TEMP error 0=no error, 1=overflow/underflow occurred
2 4 IDA0 enabled 0=disabled, 1=enabled
2 5 IDA1 enabled 0=disabled, 1=enabled
2 6 –  
2 7 –  
3 3-0 PWM0/PCA0 mode 0=off, 2=PWM8, 3=PWM16, 4=FREQ
4 3-0 PWM1/PCA1 mode 0=off, 2=PWM8, 3=PWM16, 4=FREQ
Usage:

analog_status(length=1)
Parameters:
  • length: number of status-bytes to read (0..5)
Returns:

list of status-bytes, each 0..0xFF
Raises:

AM_ERROR, LibraryNotInitialized
SeeAlso:

AdvaBoard RPi1 documentation

4.5.14   Analog-I/O / PWM: Control analog-I/Os / PWM.

Control (=start/stop/set mode) analog-I/Os of the AdvaBoard RPi1.

control may be one, or multiple or-combined values of:

  • ANALOG_CONTROL.ADC0_STOP
  • ANALOG_CONTROL.ADC0_ONESHOT
  • ANALOG_CONTROL.ADC0_CONTINUOUS
  • ANALOG_CONTROL.ADC1_STOP
  • ANALOG_CONTROL.ADC1_ONESHOT
  • ANALOG_CONTROL.ADC1_CONTINUOUS
  • ANALOG_CONTROL.ADC2_STOP
  • ANALOG_CONTROL.ADC2_ONESHOT
  • ANALOG_CONTROL.ADC2_CONTINUOUS
  • ANALOG_CONTROL.ADC3_STOP
  • ANALOG_CONTROL.ADC3_ONESHOT
  • ANALOG_CONTROL.ADC3_CONTINUOUS
  • ANALOG_CONTROL.ADC4_STOP
  • ANALOG_CONTROL.ADC4_ONESHOT
  • ANALOG_CONTROL.ADC4_CONTINUOUS
  • ANALOG_CONTROL.IDA0_DISABLE
  • ANALOG_CONTROL.IDA0_ENABLE
  • ANALOG_CONTROL.IDA1_DISABLE
  • ANALOG_CONTROL.IDA1_ENABLE
  • ANALOG_CONTROL.PWM0_DISABLE
  • ANALOG_CONTROL.PWM0_PWM8
  • ANALOG_CONTROL.PWM0_PWM16
  • ANALOG_CONTROL.PWM0_FREQ
  • ANALOG_CONTROL.PWM1_DISABLE
  • ANALOG_CONTROL.PWM1_PWM8
  • ANALOG_CONTROL.PWM1_PWM16
  • ANALOG_CONTROL.PWM1_FREQ
Usage:

analog_control(control)
Parameters:
  • control: one or more control-bits
Raises:

AM_ERROR, LibraryNotInitialized
SeeAlso:

ANALOG_CONTROL, AdvaBoard RPi1 documentation

4.5.15   Analog-I/O: Read analog-inputs.

Read the analog-inputs (AIN0..3) of the AdvaBoard RPi1.

Usage:

analogins_read()
Returns:

[ain0, ain1, ain2, ain3]

  • ain0..3: analog-values, 0..0xFFFF
Raises:

AM_ERROR, LibraryNotInitialized
Note:

This only receives the last sampled values; you also have to use am_rpi_advaboard_analog_control() to configure sampling.

4.5.16   Analog-I/O: Read a single analog-input.

Read the value of a single analog-input.

Usage:

analogin_read(i)
Parameters:
  • i: number of the analog-input (0..4)
Returns:

analog-value, 0..0xFFFF
Raises:

AM_ERROR, LibraryNotInitialized

4.5.17   Analog-I/O: Write analog-outputs.

Write analog-outputs of the AdvaBoard RPi1.

Usage:

analogouts_write(ida0, ida0_scale, ida1, ida1_scale)
Parameters:
  • ida0..1: analog-value (0..255)
  • ida0..1_scale: analog-output-scale (0..3)
Raises:

AM_ERROR, LibraryNotInitialized
Note:

scale: 0=0..0.25mA, 1=0..0.5mA, 2=0..1.0mA, 3=0..2.0mA

4.5.18   Analog-I/O: Read analog-outputs.

Read the analog-outputs (IDA0..1) of the AdvaBoard RPi1.

Usage:

analogouts_read()
Returns:

[ida0, ida0_scale, ida1, ida1_scale]

  • ida0..1: analog-values (0..255)
  • ida0..1_scale: analog-out-scale
Raises:

AM_ERROR, LibraryNotInitialized
Note:

scale: 0=0..0.25mA, 1=0..0.5mA, 2=0..1.0mA, 3=0..2.0mA

4.5.19   Analog-I/O: Write a single analog-output.

Write a single analog-output.

Usage:

analogout_write(i, value, scale)
Parameters:
  • i: number of the analog-output (0..1)
  • value: analog-value (0..255)
  • scale: analog-output-scale (0..3)
Raises:

AM_ERROR, LibraryNotInitialized
Note:

scale: 0=0..0.25mA, 1=0..0.5mA, 2=0..1.0mA, 3=0..2.0mA

4.5.20   Analog-I/O: Read a single analog-output.

Read a single analog-output.

Usage:

analogout_read(i)
Parameters:
  • i: number of the analog-output (0..1)
Returns:

analog-value (bit 0..7: value, bit 8..9: scale)
Raises:

AM_ERROR, LibraryNotInitialized

4.5.21   PWM: Configure PWM-clock.

Set the PWM-clock.

  • PWM8 repeating-frequency = 95.7kHz / (clkdiv+1) / prescaler
  • PWM16 repeating-frequency = 373.84Hz / (clkdiv+1) / prescaler
  • FREQ frequency = 12.25MHz / (clkdiv+1) / prescaler / value, (value "0" is treated as 256)

Note that the clock has a tolerance of +-2%.

Usage:

pwm_clk(clkdiv, prescaler)
Parameters:
  • clkdiv: clock-divisor (0..0xff)
  • prescaler: clock-prescaler (1/4/12/48)
Raises:

AM_ERROR, LibraryNotInitialized

4.5.22   PWM: Read PWM-clock.

Read the PWM-clock.

Usage:

pwm_clk_read()
Returns:

[clkdiv, prescaler]

  • clkdiv: clock-divisor
  • prescaler: clock-prescaler
Raises:

AM_ERROR, LibraryNotInitialized

4.5.23   PWM: Set PWM-value.

Set a PWM.

Usage:

pwm_write(i, value)
Parameters:
  • i: PWM-number (0/1)
  • value: PWM-value (0..0xffff)
Raises:

AM_ERROR, LibraryNotInitialized
Note:

The PWM-modes "PWM8" and "FREQ" only use the higher 8 bit of value.

4.5.24   PWM: Read a PWM-value.

Read a PWM-value.

Usage:

pwm_read(i)
Parameters:
  • i: PWM-number (0/1)
Returns:

PWM-value
Raises:

AM_ERROR, LibraryNotInitialized

4.5.25   PWM: Read PWM-values.

Read all PWM-values.

Usage:

pwms_read()
Returns:

[pwm0, pwm1]

  • pwm0..1: PWM-values
Raises:

AM_ERROR, LibraryNotInitialized
Note:

The PWM-modes "PWM8" and "FREQ" only use the higher 8 bit of pwm0/pwm1.

4.6   event-based automation

The microcontrollers of the AdvaBoard RPi1 contain an event-based automation, so that they can react to certain events very quickly and without the Raspberry Pi. This can remove real-time-requirements from the Raspberry Pi, and simplify many tasks.

Therefore, there are configurable events (e.g. changing inputs), which can trigger an event-handler; for every handler, the actions (e.g. set outputs) can be configured.

The AdvaBoard RPi1 has two such event-based automation systems:

  • eventpwr: switch power on/off, start Raspberry Pi etc. on RTC-alarms or I2C-interrupts
  • eventio: set/clear digital-output-pins on digital-input-changes
SeeAlso:AdvaBoard RPi1 documentation

4.6.1   power-management / RTC (eventpwr)

Events:

  • reset, always triggers handler 0
  • 5V-power-supply off / switch to battery, always triggers handler 1
  • 5V-power-supply on, always triggers handler 2
  • RTC alarm 0
  • RTC alarm 1
  • I2C interrupt

Handlers:

  • 8 configurable handlers (0..7)

Actions:

  • set power-outputs
  • set I2C-interrupt
  • control analog-I/O
4.6.1.1   Read event-handler-flags.

Read event-handler-flags. Every time an event-handler is triggered, its flag is set. The handlers 0..7 use the bits 0..7 of flags.

Usage:eventpwr_flags()
Returns:handler-flags (0..0xff)
Raises:AM_ERROR, LibraryNotInitialized
4.6.1.2   Clear event-handler-flags.

Clear some event-handler-flags.

Usage:

eventpwr_clear(flags=0xff)
Parameters:
  • flags: bitmask of handler-flags to clear (0..0xff)
Raises:

AM_ERROR, LibraryNotInitialized
4.6.1.3   Trigger event-handler.

Manually trigger an event-handler.

Usage:

eventpwr_trigger(handler_pwr)
Parameters:
  • handler_pwr: handler-number to trigger (0..7)
Raises:

AM_ERROR, LibraryNotInitialized
4.6.1.4   Handler: Configure digital-outputs.

Define which outputs should be set/cleared by an event-handler.

Usage:

eventpwr_output_write(handler_pwr, mask0, output0)
Parameters:
  • handler_pwr: handler-number to configure (0..7)
  • mask0: bitmask (0..0xff), 0=do not touch this bit, 1=set/clear this bit
  • output0: value of the outputs (0..0xff)
Raises:

AM_ERROR, LibraryNotInitialized
SeeAlso:

eventpwr_power_write()
4.6.1.5   Handler: Read digital-output-configuration.

Read which outputs are set/cleared by an event-handler.

Usage:

eventpwr_output_read(handler_pwr)
Parameters:
  • handler_pwr: handler-number
Returns:

[mask0, output0]

  • mask0: bitmask, 0=do not touch this bit, 1=set/clear this bit
  • output0: value of the outputs
Raises:

AM_ERROR, LibraryNotInitialized
SeeAlso:

eventpwr_power_read()
4.6.1.6   Handler: Configure analog-control.

Define which analog-controls should be executed by an event-handler.

Usage:

eventpwr_analogcontrol_write(handler_pwr, analogcontrol0=0, analogcontrol1=0, analogcontrol2=0)
Parameters:
  • handler_pwr: handler-number to configure (0..7)
  • analogcontrol0..2: analog-control-bytes 0..2
Raises:

AM_ERROR, LibraryNotInitialized
Note:

analogcontrol0..1 control the ADC, analogcontrol2 controls the RTC
4.6.1.7   Handler: Read analog-control-configuration.

Read which analog-controls are executed by an event-handler.

Usage:

eventpwr_analogcontrol_read(handler_pwr)
Parameters:
  • handler_pwr: handler-number
Returns:

[analogcontrol0, analogcontrol1, canalogcontrol2]
Raises:

AM_ERROR, LibraryNotInitialized
4.6.1.8   Handler: Configure power-on/off.

Configure which parts of the AdvaBoard RPi1 should be powered-on/off by an event-handler.

Every parameter can have 3 values:

value meaning
-1, <0 do not change
0 power-off
1, >0 power-on
Usage:

eventpwr_power_write(handler_pwr, pwron=-1, cpld_3v=-1, peripheral_5v=-1, rpi=-1, tft=-1, tft_backlight=-1)
Parameters:
  • handler_pwr: handler-number to configure
  • pwron: 5V-power-supply power-on/off
  • cpld_3v: CPLD and peripheral 3.3V (CPLD-I/O, RS-232-3.3V, Flash)
  • peripheral_5v: peripheral 5V (RS-485, E-SPI, RS-232-5V)
  • rpi: Raspberry Pi
  • tft: TFT-display incl. backlight of 4.3"/5.0"
  • tft_backlight: TFT-backlight of 2.4"/3.2"/7.0"
Raises:

AM_ERROR, LibraryNotInitialized
4.6.1.9   Handler: Read power-on/off-configuration.

Read which parts of the AdvaBoard RPi1 are powered-on/off by an event-handler.

Usage:

eventpwr_power_read(handler_pwr)
Parameters:
  • handler_pwr: handler-number
Returns:

[pwron, cpld_3v, peripheral_5v, rpi, tft, tft_backlight]

  • pwron: 5V-power-supply power-on/off
  • cpld_3v: CPLD and peripheral 3.3V (CPLD-I/O, RS-232-3.3V, Flash)
  • peripheral_5v: peripheral 5V (RS-485, E-SPI, RS-232-5V)
  • rpi: Raspberry Pi
  • tft: TFT-display incl. backlight of 4.3"/5.0"
  • tft_backlight: TFT-backlight of 2.4"/3.2"/7.0"
Raises:

AM_ERROR, LibraryNotInitialized
4.6.1.10   Event: Define handler for I2C-interrupt.

Define which handler should be executed when an I2C-interrupt occurs.

Usage:

eventpwr_i2cint_write(handler_pwr_en)
Parameters:
  • handler_pwr_en: handler-number to trigger + 0x80 to enable or 0x00 to disable
Raises:

AM_ERROR, LibraryNotInitialized
4.6.1.11   Event: Read handler for I2C-interrupt.

Read which handler is executed when an I2C-interrupt occurs.

Usage:eventpwr_i2cint_read()
Returns:handler-number + 0x80 if the event is enabled
Raises:AM_ERROR, LibraryNotInitialized
4.6.1.12   Event: Define RTC-alarm.

Define a RTC-alarm and which handler should be executed when the RTC-alarm occurs.

Usage:

rtc_alarm_write(i, handler_pwr, time, periodic=0)
Parameters:
  • i: RTC-alarm-number (0/1)
  • handler_pwr: handler-number (0..7)
  • time: RTC-alarm-time in 32-bit seconds, if < 0x10000000, the alarm is relative to the current time
  • periodic: periodicity in 24-bit seconds (0..16777215), 0=no periodic alarm, others=repeat alarm every periodic seconds
Raises:

AM_ERROR, LibraryNotInitialized
Note:
  • Old alarms (with alarm-time < current time) are executed once immediately; if they are periodic, they are executed once for the past, and periodically in the future.
  • Old alarms can occur in several circumstances:
  • an alarm is defined, but alarm-time < current time
  • an alarm is defined, then the RTC-time is set
  • a periodic alarm is defined, then the alarm is disabled and later enabled again.

Be careful with old periodic alarms! If you use e.g. a 5-seconds-periodic alarm, and then set the RTC-time 1 year forwards, the device may be unaccessible for several minutes until it has catched up the current time!

  • Note that the alarm also has to be enabled by using AM_RPI_ADVABOARD_RTC_ALARM0_ON / _ALARM1_ON or am_rpi_advaboard_rtc_alarm_set().
4.6.1.13   Event: Define RTC-alarm and activate it.

Define a RTC-alarm and which handler should be executed when the RTC-alarm occurs, and activate it. This is a simple wrapper around rtc_alarm_write() and rtc_control().

Usage:

rtc_alarm_set(i, handler_pwr, time, periodic=0)
Parameters:
  • i: RTC-alarm-number (0/1)
  • handler_pwr: handler-number (0..7)
  • time: RTC-alarm-time in 32-bit seconds, if < 0x10000000, the alarm is relative to the current time
  • periodic: periodicity in 24-bit seconds (0..16777215), 0=no periodic alarm, others=repeat alarm every periodic seconds
Raises:

AM_ERROR, LibraryNotInitialized
SeeAlso:

rtc_alarm_write(), rtc_control()
4.6.1.14   Event: Read RTC-alarm.

Read RTC-alarm and which handler is executed when the RTC-alarm occurs.

Usage:

rtc_alarm_read(i)
Parameters:
  • i: RTC-alarm-number (0/1)
Returns:

[handler_pwr, time, periodic]

  • handler_pwr: handler-number (0..7)
  • time: RTC-alarm-time in 32-bit seconds
  • periodic: periodicity in 24-bit seconds (0..16777215), 0=no periodic alarm
Raises:

AM_ERROR, LibraryNotInitialized
Note:

For periodic alarms, time returns the absolute time for the next alarm.

4.6.2   I/O (eventio)

Events:

  • reset, always triggers handler 0
  • 4 configurable events, depending on the digital-inputs I/O 0.4..0.7, 1.0..1.7

Handlers:

  • 4 handlers with configurable actions (0..3)

Actions:

  • set digital-outputs 0.4..0.7, 1.0..1.7
  • control digital-I/Os 0.4..0.7, 1.0..1.7
4.6.2.1   Read event-handler-flags.

Read event-handler-flags. Every time an event-handler is triggered, its flag is set. The handlers 0..3 use the bits 0..3 of flags.

Usage:eventio_flags()
Returns:handler-flags (0..0x0f)
Raises:AM_ERROR, LibraryNotInitialized
4.6.2.2   Clear event-handler-flags.

Clear some event-handler-flags.

Usage:

eventio_clear(flags=0x0f)
Parameters:
  • flags: bitmask of handler-flags to clear (0..0x0f)
Raises:

AM_ERROR, LibraryNotInitialized
4.6.2.3   Trigger event-handler.

Manually trigger an event-handler.

Usage:

eventio_trigger(handler_io)
Parameters:
  • handler_io: handler-number to trigger (0..3)
Raises:

AM_ERROR, LibraryNotInitialized
4.6.2.4   Handler: Configure digital-outputs.

Define which outputs should be set/cleared by an event-handler.

Usage:

eventio_output_write(handler_io, mask0=0, output0=0, mask1=0, output1=0, mask2=0, output2=0)
Parameters:
  • handler_io: handler-number to configure (0..3)
  • mask0: bitmask for I/O 0.4..0.7 (0..0xff), 0=do not touch this bit, 1=set/clear this bit
  • output0: value of the outputs 0.4..0.7 (0..0xff)
  • mask1: bitmask for I/O 1.0..1.7 (0..0xff), 0=do not touch this bit, 1=set/clear this bit
  • output1: value of the outputs 1.0..1.7 (0..0xff)
  • mask2: bitmask for F353-output-byte 2 (0..0xff), 0=do not touch this bit, 1=set/clear this bit
  • output2: value of the F353-output-byte 2 (0..0xff, see notes)
Raises:

AM_ERROR, LibraryNotInitialized
Note:

The F353-output-byte 2 is a virtual output, with:

bit

description

values

0

I2C-interrupt

0=I2C_INT low, 1=high (default)

3

RS-MUX

0=select RS-485, 1=select RS-232

4

RS-485 bit9

0=no bit-insertion, 1=insert 9th bit for RS-485 device-addressing

5

ESPI-pins-enable

0=disable E-SPI-pins, 1=enable ESPI-pins

6

RPi-pins-enable

0=disable RPi-pins, 1=enable RPi-pins

7

TFT-pins-enable

0=disable TFT-pins, 1=enable TFT-pins
SeeAlso:

AdvaBoard RPi1 documentation
4.6.2.5   Handler: Read digital-output-configuration.

Read which outputs are set/cleared by an event-handler.

Usage:

eventio_output_read(handler_io)
Parameters:
  • handler_io: handler-number (0..3)
Returns:

[mask0, output0, mask1, output1, mask2, output2]

  • mask0: bitmask for I/O 0.4..0.7 (0..0xff)
  • output0: value of the outputs 0.4..0.7 (0..0xff)
  • mask1: bitmask for I/O 1.0..1.7 (0..0xff)
  • output1: value of the outputs 1.0..1.7 (0..0xff)
  • mask2: bitmask for F353-output-byte 2 (0..0xff)
  • output2: value of the F353-output-byte 2 (0..0xff)
Raises:

AM_ERROR, LibraryNotInitialized
SeeAlso:

AdvaBoard RPi1 documentation
4.6.2.6   Handler: Configure digital-control.

Define which digital-controls should be executed by an event-handler.

Usage:

eventio_control_write(handler_io, control)
Parameters:
  • handler_io: handler-number to configure (0..3)
  • control: digital-control
Raises:

AM_ERROR, LibraryNotInitialized
SeeAlso:

io_control(), IO_CONTROL, AdvaBoard RPi1 documentation
4.6.2.7   Handler: Read digital-control-configuration.

Read which digital-controls are executed by an event-handler.

Usage:

eventio_control_read(handler_io)
Parameters:
  • handler_io: handler-number (0..3)
Returns:

digital-control
Raises:

AM_ERROR, LibraryNotInitialized
SeeAlso:

IO_CONTROL, AdvaBoard RPi1 documentation
4.6.2.8   Event: Configure event.

Configure an event. When the I/Os match the configured value, an event-handler is triggered.

Usage:

eventio_event_write(event_io, handler_io, mask0, input0, mask1, input1)
Parameters:
  • event_io: event-number to configure (0..3)
  • handler_io: handler-number to trigger (0..3)
  • mask0: bitmask for I/Os 0.4..0.7 (0..0xff), 0=ignore input, 1=watch input
  • input0: match-value for I/Os 0.4..0.7 (0..0xff)
  • mask1: bitmask for I/Os 1.0..1.7 (0..0xff), 0=ignore input, 1=watch input
  • input1: match-value for I/Os 1.0..1.7 (0..0xff)
Raises:

AM_ERROR, LibraryNotInitialized
4.6.2.9   Event: Read event-configuration.

Read an event-configuration.

Usage:

eventio_event_read(event_io)
Parameters:
  • event_io: event-number (0..3)
Returns:

[handler_io, mask0, input0, mask1, input1]

  • handler_io: handler-number (0..3)
  • mask0: bitmask for I/Os 0.4..0.7
  • input0: match-value for I/Os 0.4..0.7
  • mask1: bitmask for I/Os 1.0..1.7
  • input1: match-value for I/Os 1.0..1.7
Raises:

AM_ERROR, LibraryNotInitialized

4.7   EEPROM

4.7.1   Store F912-configuration in EEPROM.

Store the current configuration of the F912 to its EEPROM, from which it is loaded after reset / power-off/on.

The stored configuration contains:

  • communication-parameters (I2C-clock-extension / I2C-clock-extension-injection)
  • I2C-interrupt-event
  • I/O-event-handlers (power-on/off at event, I2C-interrupt at event), incl. power-on/off directly after reset
  • ADC- and RTC-event-handlers (ADC-modes, RTC-start/stop/alarm-enable), incl. modes directly after reset
Usage:f912_store()
Raises:AM_ERROR, LibraryNotInitialized

4.7.2   Store F353-configuration in EEPROM.

Store the current configuration of the F353 to its EEPROM, from which it is loaded after reset / power-off/on.

The stored configuration contains:

  • communication-parameters (I2C-clock-extension, RS-485-speed)
  • I/O-configuration of I/O 0.4..0.7, 1.0..1.7 (input/output/output_opendrain/output_pushpull)
  • PWM-clock
  • I/O-events
  • I/O-handlers (output / control / pins at handler), incl. output-values, I/O-control and enabled pins directly after reset
Usage:f353_store()
Raises:AM_ERROR, LibraryNotInitialized

4.8   E-SPI-interface

This library supports concurrent access to the E-SPI from different programs, which use this library, by using automatic locks.

If you want to use E-SPI, the TFT-display/-touchpanel/-SD-card or any other SPI-communication from different threads in a program, use e.g. a SPI-mutex to make sure only 1 thread accesses the SPI at the same time. If the threads use different E-SPI-configurations, make sure to reconfigure the E-SPI after acquiring the mutex.

SeeAlso:AdvaBoard RPi1 documentation

4.8.1   Communicate with E-SPI-devices.

Communicate with an E-SPI-device (incl. auto-locking).

Usage:

espi(sel, txdata)
Parameters:
  • sel: E-SPI SEL0..3 value (0..0x0F, -1=don't change)
  • txdata: transmit-data (bytestring or list of 0..0xFF)
Returns:

received data (bytestring)
Raises:

AM_ERROR, LibraryNotInitialized

4.8.2   Configure E-SPI-clock.

Configure the E-SPI on the AdvaBoard RPi.

The valid clock-phases and -polarities are:

  • SPI_CLKCFG.IDLELOW_SHIFTFALLING_READRISING
  • SPI_CLKCFG.IDLELOW_SHIFTRISING_READFALLING
  • SPI_CLKCFG.IDLEHIGH_SHIFTRISING_READFALLING (default)
  • SPI_CLKCFG.IDLEHIGH_SHIFTFALLING_READRISING
Usage:

espi_clk(clkdiv=-1, clkcfg=-1)
Parameters:
  • clkdiv: SPI clock-divisor (SPI_CLK.* or 4/6/8..65536, -1=don't change)
  • clkcfg: SPI clock polarity and clock phase (-1=don't change)
Raises:

AM_ERROR (AM_ERROR_CODE: INVALID_ARGUMENT), LibraryNotInitialized
Note:
  • SPI-speed is 250 MHz / clkdiv
  • Note that this only sets some internal variables and doesn't configure the hardware immediately; instead, the hardware is configured before every E-SPI-communication, to enable concurrent access to the SPI.
SeeAlso:

SPI_CLKCFG, SPI_CLK

4.8.3   E-SPI SEL0..3: Set select-pins.

Set E-SPI select-pins (incl. E-SPI-locking).

Usage:

espi_sel(sel)
Parameters:
  • sel: E-SPI SEL0..3 value (0..0x0F)
Raises:

AM_ERROR, LibraryNotInitialized

4.8.4   E-SPI SEL0..3: Read select-pins.

Read E-SPI select-pins.

Usage:espi_sel_read()
Returns:E-SPI SEL0..3 value (0..0x0F)
Raises:AM_ERROR, LibraryNotInitialized
Note:This returns the current levels, which may differ from the value set by am_rpi_advaboard_espi_sel() if the E-SPI is not locked.

4.8.5   Read E-SPI-interrupt.

Read the E-SPI-interrupt (incl. E-SPI-locking).

Usage:espi_int_read()
Returns:False if no interrupt, True on interrupt
Raises:AM_ERROR (AM_ERROR_CODE: BUSY), LibraryNotInitialized
SeeAlso:AdvaBoard RPi1 documentation

4.8.6   Manually lock E-SPI.

Manually lock E-SPI for several communications.

Note that you additionally have to use a mutex, if you're accessing the SPI from several threads in the same program.

Usage:

espi_lock(timeout_ms=-1)
Parameters:
  • timeout_ms: timeout in ms (0..65535), 0=non-blocking, -1/omitted=use auto-locking-timeout
Raises:

AM_ERROR (AM_ERROR_CODE: BUSY after timeout), LibraryNotInitialized

4.8.7   Manually unlock E-SPI.

Unlock E-SPI again after espi_lock(). This has to be used for every successful call to espi_lock().

Usage:espi_unlock()
Raises:LibraryNotInitialized

4.8.8   Set E-SPI auto-locking-timeout.

Set timeout, after which E-SPI-communication-functions raise AM_ERROR(AM_ERROR_CODE.BUSY) if they cannot lock the E-SPI.

Usage:

espi_locking_timeout(timeout_ms)
Parameters:
  • timeout_ms: timeout in ms (0..65535, default: 1000ms)
Raises:

LibraryNotInitialized

4.9   I2C-interface

This library supports concurrent access to the I2C from different programs, which use this library, by using automatic locks.

If you want to use the I2C-interface, the F912/F353, the power-management, RTC, I/O, event-based automation, EEPROM, RS-485-configuration, or any other I2C-communication from different threads in a program, use e.g. a I2C-mutex to make sure only 1 thread accesses the I2C-bus at the same time. If the threads use different I2C-configurations, make sure to reconfigure the I2C after acquiring the mutex.

SeeAlso:AdvaBoard RPi1 documentation

4.9.1   Communicate with I2C-devices.

Communicate with I2C-devices, which are connected to the AdvaBoard RPi1.

Usage:

i2c(address, txdata=b'', rxlen=0)
Parameters:
  • address: 7-bit I2C-slave address
  • txdata: transmit-data (bytestring or list of 0..0xFF, max. 65535 bytes)
  • rxlen: number of bytes to read (max. 65535)
Returns:

received data (bytestring)
Raises:

AM_ERROR, LibraryNotInitialized
SeeAlso:

rpi.i2c_write_read()

4.9.2   Communication with I2C-devices with the Advamation RS-485-/I2C-protocol.

Communicate with I2C-devices, which are connected to the AdvaBoard RPi1, with the Advamation RS-485-/I2C-protocol (incl. CRC/PEC).

Usage:

i2c_prot(address, cmd, txdata=b"")
Parameters:
  • address: 7-bit I2C-slave address
  • cmd: I2C-protocol-command (AM_CMD.*)
  • txdata: transmit-data-bytes (bytestring or list of 0..0xFF, 0..16 bytes)
Returns:

received data (bytestring)
Raises:

AM_ERROR, LibraryNotInitialized
SeeAlso:

advamation.AM_CMD, rpi.i2c_prot()

4.9.3   Set I2C-clock.

Set the I2C-clock.

Usage:

i2c_clk(clkdiv)
Parameters:
  • clkdiv: I2C-clock-divisor (I2C_CLK.CLK...kHz or 4/6/8/.../65536)
Raises:

AM_ERROR (AM_ERROR_CODE: INVALID_ARGUMENT), LibraryNotInitialized
Note:

The I2C core clock is 250 MHz; default-clkdiv is 1500 (166.7kHz). (The Raspberry Pi datasheet is wrong, here.)
SeeAlso:

I2C_CLK.*

4.9.4   Read I2C-/SMBus-interrupt.

Read the I2C-/SMBus-interrupt.

Usage:i2c_int_read()
Returns:False if no interrupt, True on interrupt
Raises:LibraryNotInitialized
SeeAlso:AdvaBoard RPi1 documentation

4.9.5   Clear I2C-INT-pin of F912.

Set the I2C-interrupt-pin of F912-microcontroller to high. Can be used to release the interrupt again after the F912-microcontroller of the AdvaBoard RPi1 has caused an I2C-interrupt.

Usage:i2c_f912int_clear()
Raises:AM_ERROR, LibraryNotInitialized
SeeAlso:AdvaBoard RPi1 documentation

4.9.6   Manually lock I2C.

Manually lock I2C for several subsequent communications.

Note that you additionally have to use a mutex, if you're accessing the I2C-bus from several threads in the same program.

Usage:

i2c_lock(timeout_ms=-1)
Parameters:
  • timeout_ms: timeout in ms (0..65535), 0=non-blocking, -1/omitted=use auto-locking-timeout
Raises:

AM_ERROR (AM_ERROR_CODE: BUSY after timeout), LibraryNotInitialized

4.9.7   Manually unlock I2C.

Unlock I2C again after i2c_lock(). This must be used for every successful call to i2c_lock().

Usage:i2c_unlock()
Raises:LibraryNotInitialized

4.9.8   Set I2C auto-locking-timeout.

Set timeout, after which I2C-communication-functions raise AM_ERROR(AM_ERROR_CODE.BUSY) if they cannot lock the I2C.

Usage:

i2c_locking_timeout(timeout_ms)
Parameters:
  • timeout_ms: timeout in ms (0..65535, default: 1000ms)
Raises:

LibraryNotInitialized

4.9.9   I2C-clock-stretching: Configure.

The Raspberry Pi has a bug, which causes problems when communicating with I2C-devices which use clock-stretching. Some of these problems can be resolved by making sure that clock-stretches in the ACK-phase are always longer than a minimum value.

For this, the AdvaBoard RPi1 can

  • use a minimum clock-stretching in its internal communication to its F912/F353
  • inject clock-stretching in the ACK-phase into the I2C-communication with other devices (see am_rpi_advaboard_i2c_clkextinj()).

The delay should be about 1 bit time, so:

delay >= 24.5MHz / I2C_clock / 32 * 105%

e.g. delay=8 for an I2C-clock of 100 kHz.

Usage:

i2c_clkext(delay)
Parameters:
  • delay: clock-stretching-delay to inject (0..0xFF)
Raises:

AM_ERROR, LibraryNotInitialized
SeeAlso:

http://www.advamation.com/knowhow/raspberrypi/rpi-i2c-bug.html

4.9.10   I2C-clock-stretching: Read configured delay.

Read the configured delay for I2C-clock-stretching and I2C-clock-stretching-injection.

Usage:

i2c_clkext_read()
Returns:

[delay, delay353]

  • delay: clock-stretching-delay of F912/clock-injection
  • delay353: clock-stretching-delay of F353
Raises:

AM_ERROR, LibraryNotInitialized

4.9.11   I2C-clock-stretching: Configure injection.

Inject clock-stretching-delays in the ACK-phase for some I2C-devices. The length of the delay is configured by i2c_clkext().

The delay is injected in communications with I2C-devices where I2C_device_address & address_mask == address & address_mask.

Usage:

i2c_clkextinj(addressmask, address)
Parameters:
  • addressmask: mask for address (0..0xFF)
  • address: addresses for clock-stretching-injection (0..0xFF)
Raises:

AM_ERROR, LibraryNotInitialized
Note:
  • disable clock-stretching-injection: use 0xff 0xff
  • enable clock-stretching-injection for all devices: use 0x00 0x00
SeeAlso:

i2c_clkext(), http://www.advamation.com/knowhow/raspberrypi/rpi-i2c-bug.html

4.9.12   I2C-clock-stretching: Read configured injection.

Read the configured addresses for I2C-clock-stretching-injection.

Usage:i2c_clkextinj_read()
Returns:[addressmask, address]
Raises:AM_ERROR, LibraryNotInitialized

4.10   RS-232 / RS-485

4.10.1   Configure RS-485 / RS-232.

Configure the RS-485/RS-232 interface.

Usage:

rs485_cfg(mux=-1, speed=-1, bit9=-1)
Parameters:
  • mux: UART-MUX, 0=RS-485, 1=RS-232, -1=don't change
  • speed: RS-485-speed for RS-485 direction and 9.bit, -1=don't change
  • bit9: 9.bit insertion for RS-485-addressing, 0=disable, 1=enable, -1=don't change
Raises:

AM_ERROR, LibraryNotInitialized
Note:
  • speed is the time of 8 bits of the used baudrate (in 1/24.5MHz)
  • speed = 196 000 000/baudrate
  • working baudrate-range: 4477 bps up to probably about 2 Mbps

4.10.2   Read RS-485/RS-232 configuration.

Read the RS-485/RS-232 configuration.

Usage:

rs485_cfg_read()
Returns:

[mux, speed, bit9]

  • mux: UART-MUX, 0=RS-485, 1=RS-232
  • speed: RS-485-speed for RS-485 DIR/9.bit
  • bit9: 9.bit insertion, False=disable, True=enable
Raises:

AM_ERROR, LibraryNotInitialized

4.11   misc

4.11.1   Set LED.

Set the LED of the AdvaBoard RPi1.

  • 0x00: off
  • 0xff: on
  • 0x01: blink, about 3 times per second
  • 0x02: blink, about 1.5 times per second
  • 0x04: blink, about 0.8 times per second
  • 0x08: blink, about 0.4 times per second
Usage:

led(mode)
Parameters:
  • mode: on/off/blink-mode (0..0xFF)
Raises:

AM_ERROR, LibraryNotInitialized
SeeAlso:

AdvaBoard RPi1-documentation / Advamation RS-485-/I2C-protocol for blink-modes