Library for AdvaBoard RPi1 - Java binding
Version: | 2014-06-26 |
---|---|
Status: | beta |
SeeAlso: | AdvaBoard RPi1 documentation, *.java |
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: | java.am_rpi_advaboard.txt,v 1.11 2014/05/21 10:26:40 rk Exp |
Note: This library is a JNI-interface to the AdvaBoard RPi1 C-Library.
Table of contents
- 1 generic usage
- 2 init / exit / logging
- 3 basic / low-level access to the AdvaBoard RPi1
- 3.1 F912: communicate with AdvaBoard RPi1 - F912 microcontroller
- 3.2 F912: check command-status
- 3.3 F912: manually lock AdvaBoard RPi1 - F912 microcontroller
- 3.4 F912: manually unlock AdvaBoard RPi1 - F912 microcontroller
- 3.5 F912: set auto-locking-timeout
- 3.6 F353: communicate with AdvaBoard RPi1 - F353 microcontroller
- 3.7 F353: check command-status
- 3.8 F353: manually lock AdvaBoard RPi1 - F353 microcontroller
- 3.9 F353: manually unlock AdvaBoard RPi1 - F353 microcontroller
- 3.10 F353: set auto-locking-timeout
- 3.11 CPLD: communicate with AdvaBoard RPi1 - CPLD
- 3.12 GPIOs: write Raspberry Pi GPIOs
- 3.13 GPIOs: read Raspberry Pi GPIOs
- 3.14 SPI: set clock
- 3.15 SPI: set clock-phase/-polarity
- 3.16 SPI: set MUX
- 3.17 SPI: communicate
- 3.18 SPI: manually lock
- 3.19 SPI: manually unlock
- 3.20 SPI: set auto-locking-timeout
- 3.21 I2C: communicate
- 3.22 I2C: set clock
- 3.23 I2C: manually lock
- 3.24 I2C: manually unlock
- 3.25 I2C: set auto-locking-timeout
- 4 AdvaBoard RPi1 functions
- 4.1 system information
- 4.2 Status
- 4.3 Power-Management
- 4.4 RTC
- 4.5 I/O
- 4.5.1 I/O-configuration: configure digital-I/Os 0.4..0.7
- 4.5.2 I/O-configuration: read configuration of digital-I/Os 0.4..0.7
- 4.5.3 I/O-configuration: configure digital-I/Os 1.0..1.7
- 4.5.4 I/O-configuration: read configuration of digital-I/Os 1.0..1.7
- 4.5.5 digital-I/O: read status
- 4.5.6 digital-I/O: control digital-I/Os / events
- 4.5.7 digital-I/O: write outputs
- 4.5.8 digital-I/O: read I/Os 0.4..0.7
- 4.5.9 digital-I/O: read all I/Os
- 4.5.10 digital-I/O: set an output-pin to high
- 4.5.11 digital-I/O: clear an output-pin to low
- 4.5.12 digital-I/O: get level of a I/O-pin
- 4.5.13 analog-I/O: read status
- 4.5.14 analog-I/O, PWM: control analog-I/Os / PWM
- 4.5.15 analog-I/O: read analog-inputs
- 4.5.16 analog-I/O: read a single analog-input
- 4.5.17 analog-I/O: write analog-outputs
- 4.5.18 analog-I/O: read analog-outputs
- 4.5.19 analog-I/O: write a single analog-output
- 4.5.20 analog-I/O: read a single analog-output
- 4.5.21 PWM: configure PWM-clock
- 4.5.22 PWM: read PWM-clock
- 4.5.23 PWM: set PWM-value
- 4.5.24 PWM: read a PWM-value
- 4.5.25 PWM: read PWM-values
- 4.6 event-based automation
- 4.6.1 power-management / RTC (eventpwr)
- 4.6.1.1 read event-handler-flags
- 4.6.1.2 clear event-handler-flags
- 4.6.1.3 trigger event-handler
- 4.6.1.4 handler: configure digital-outputs
- 4.6.1.5 handler: read digital-output-configuration
- 4.6.1.6 handler: configure analog-control
- 4.6.1.7 handler: read analog-control-configuration
- 4.6.1.8 handler: configure power-on/off
- 4.6.1.9 handler: read power-on/off-configuration
- 4.6.1.10 event: define handler for I2C-interrupt
- 4.6.1.11 event: read handler for I2C-interrupt
- 4.6.1.12 event: define RTC-alarm
- 4.6.1.13 event: define RTC-alarm and activate it
- 4.6.1.14 event: read RTC-alarm
- 4.6.2 I/O (eventio)
- 4.6.2.1 read event-handler-flags
- 4.6.2.2 clear event-handler-flags
- 4.6.2.3 trigger event-handler
- 4.6.2.4 handler: configure digital-outputs
- 4.6.2.5 handler: read digital-output-configuration
- 4.6.2.6 handler: configure digital-control
- 4.6.2.7 handler: read digital-control-configuration
- 4.6.2.8 event: configure event
- 4.6.2.9 event: read event-configuration
- 4.6.1 power-management / RTC (eventpwr)
- 4.7 EEPROM
- 4.8 E-SPI-interface
- 4.9 I2C-interface
- 4.9.1 communicate with I2C-devices
- 4.9.2 communication with I2C-devices with the Advamation RS-485-/I2C-protocol
- 4.9.3 set I2C-clock
- 4.9.4 read I2C-/SMBus-interrupt
- 4.9.5 clear I2C-INT-pin of F912
- 4.9.6 manually lock I2C
- 4.9.7 manually unlock I2C
- 4.9.8 set I2C auto-locking-timeout
- 4.9.9 I2C-clock-stretching: configure
- 4.9.10 I2C-clock-stretching: read configured delay
- 4.9.11 I2C-clock-stretching: configure injection
- 4.9.12 I2C-clock-stretching: read configured injection
- 4.10 RS-232 / RS-485
- 4.11 misc
1 generic usage
Before using the library, it has to be imported, e.g.:
import am_rpi.advaboard; import am_rpi.AM_ERROR_Exception; import static am_rpi.advamation.I; // optionally: import am_rpi.advamation; import am_rpi.AM_ERROR_CODE; import am_rpi.AM_LOG_LEVEL; import am_rpi.AM_CMD; import am_rpi.ADVABOARD_CONFIG_IO; import am_rpi.ADVABOARD_IO_CONTROL; import am_rpi.ADVABOARD_ANALOG_CONTROL; import am_rpi.ADVABOARD_RTC_CONTROL; import am_rpi.ADVABOARD_RTC_STATUS; import am_rpi.ADVABOARD_GPIO; import am_rpi.ADVABOARD_SPI_CLKCFG;
The functions usually throw AM_ERROR_Exception on error, so always catch it, e.g.:
try { advaboard.init(0); advaboard.led(0x02); } catch(AM_ERROR_Exception e) { System.out.println("Exception: " + e.getMessage()); }
In addition, they may throw IllegalArgumentException if the parameters are out-of-range (e.g. for negative values where no negative values are allowed, for values > 0xFF, 0xFFFF or 0xFFFFFFFF when a value between 0 and 0xFF/0xFFFF/0xFFFFFFFF was expected). An IllegalArgumentException always indicates a bug in your code which called the function.
Many functions take or return several (raw) bytes, e.g. bytes to send via I2C or bytes received from I2C. These are implemented as int-arrays in Java (int[], with each element containing 0..0xFF), so they can be used without lots of manual casts [1]. If such an int[]-parameter is fixed (as they often are in e.g. I2C-communications), it can be created on-the-fly in several ways, e.g.:
# use an anonymous array advaboard.i2c(0x29, new int[] {0x80, 0x12, 0x34}, 1); # use an integer-array-creator shortcut import static am_rpi.advamation.I; advaboard.i2c(0x29, I(0x80, 0x12, 0x34), 1);
Some example-programs can be found in the example-directory.
[1] | Unfortunately, Java does not offer an "unsigned byte" data-type, and unfortunately, Java does not check and down-cast integer constants (like e.g. 1) at compile-time. This can make code which works with the byte-type quite unreadable, e.g. if this library would use the byte-datatype, you would have to write: # (not used here) advaboard.i2c((byte)0x29, new byte[] {(byte)0x80, 0x12, 0x34}, 1); instead of: # (used here) advaboard.i2c(0x29, I(0x80, 0x12, 0x34), 1); So, the int-datatype is used here, to make programming easier and to make it possible to write readable code. |
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. advaboard.init() and advaboard.exit() must always be called pairwise.
Usage: | void advaboard.init() |
---|---|
Throws: | AM_ERROR_Exception on error |
2.2 exit library
De-initialize the library. Must be used for every successful call of advaboard.init().
Usage: | void advaboard.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: | void advaboard.logging(int level, String logfile, int logfile_level) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error
(AM_ERROR_CODE.INVALID_ARGUMENT, AM_ERROR.IO if the logfile cannot be opened)
|
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: | int[] advaboard.f912_comm(int cmd, int[] txdata, int rxlen) |
---|---|
Parameters: |
|
Returns: | received bytes (array of 0..0xFF values) |
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
SeeAlso: | AM_CMD, AdvaBoard RPi1 documentation, Advamation RS485-/I2C-protocol |
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: | int f912_cmdstatus() |
---|---|
Returns: | command-status (0: done, >0: busy) |
Throws: | AM_ERROR_Exception on error |
Note: | This is only supported if the AdvaBoard RPi1-firmware is >= 20140219. For older firmware, AM_ERROR_CODE.NOT_IMPLEMENTED is thrown. |
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: | void advaboard.f912_lock() void advaboard.f912_lock(int timeout_ms) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error
(AM_ERROR_CODE.BUSY after timeout)
|
3.4 F912: manually unlock AdvaBoard RPi1 - F912 microcontroller
Unlock the F912 again after advaboard.f912_lock(). This has to be used for every successful call to advaboard.f912_lock().
Usage: | void advaboard.f912_unlock() |
---|
3.5 F912: set auto-locking-timeout
Set timeout, after which F912-communication-functions throw AM_ERROR(AM_ERROR_CODE.BUSY) if they cannot lock the F912.
Usage: | void advaboard.f912_locking_timeout(int timeout_ms) |
---|---|
Parameters: |
|
Throws: | IllegalArgumentException for out-of-range parameters |
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: | int[] advaboard.f353_comm(int cmd, int[] txdata, int rxlen) |
---|---|
Parameters: |
|
Returns: | received bytes (array of 0..0xFF values) |
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
SeeAlso: | AM_CMD, AdvaBoard RPi1 documentation, Advamation RS485-/I2C-protocol |
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: | int f912_cmdstatus() |
---|---|
Returns: | command-status (0: done, >0: busy) |
Throws: | AM_ERROR_Exception on error |
Note: | This is only supported if the AdvaBoard RPi1-firmware is >= 20140219. For older firmware, AM_ERROR_CODE.NOT_IMPLEMENTED is thrown. |
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: | void advaboard.f353_lock() void advaboard.f353_lock(int timeout_ms) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error
(AM_ERROR_CODE.BUSY after timeout)
|
3.9 F353: manually unlock AdvaBoard RPi1 - F353 microcontroller
Unlock the F353 again after advaboard.f353_lock(). This has to be used for every successful call to advaboard.f353_lock().
Usage: | void advaboard.f353_unlock() |
---|
3.10 F353: set auto-locking-timeout
Set timeout, after which F353-communication-functions throw AM_ERROR(AM_ERROR_CODE.BUSY) if they cannot lock the F353.
Usage: | void advaboard.f353_locking_timeout(int timeout_ms) |
---|---|
Parameters: |
|
Throws: | IllegalArgumentException for out-of-range parameters |
3.11 CPLD: communicate with AdvaBoard RPi1 - CPLD
Write/read registers of the Xilinx CPLD of the AdvaBoard RPi1.
Usage: | int[] advaboard.cpldreg(int[] tx) |
---|---|
Parameters: |
|
Returns: | received byte(s) (array of 0..0xFF values) |
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
SeeAlso: | AdvaBoard RPi1 documentation |
3.12 GPIOs: write Raspberry Pi GPIOs
Set/clear Raspberry Pi GPIOs, which are connected to the AdvaBoard RPi1.
Valid GPIOs:
- ADVABOARD_GPIO.RPi_SEL0
- ADVABOARD_GPIO.RPi_SEL1
- ADVABOARD_GPIO.RPi_SEL2
- ADVABOARD_GPIO.RPi_SEL3
- ADVABOARD_GPIO.RPi_PWM
- ADVABOARD_GPIO.LCD_RS
Usage: | void advaboard.gpio_write(long gpios, boolean level) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
(AM_ERROR_CODE.INVALID_ARGUMENT)
IllegalArgumentException for out-of-range parameters
|
SeeAlso: | ADVABOARD_GPIO, AdvaBoard RPi1 documentation |
3.13 GPIOs: read Raspberry Pi GPIOs
Read Raspberry Pi GPIOs, which are connected to the AdvaBoard RPi1.
Usual GPIOs:
- ADVABOARD_GPIO.I2C_INT
- ADVABOARD_GPIO.TP_INT
- ADVABOARD_GPIO.RPi_PWM
- ADVABOARD_GPIO.RPi_SEL0
- ADVABOARD_GPIO.RPi_SEL1
- ADVABOARD_GPIO.RPi_SEL2
- ADVABOARD_GPIO.RPi_SEL3
- ADVABOARD_GPIO.SPI_MISO
Usage: | long advaboard.gpio_read(long gpios) |
---|---|
Parameters: |
|
Returns: | current input levels, masked by gpios |
Throws: | IllegalArgumentException for out-of-range parameters. |
SeeAlso: | ADVABOARD_GPIO, AdvaBoard RPi1 documentation |
3.14 SPI: set clock
Set the SPI-clock.
Usage: | void advaboard.spi_clk(int clkdiv) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error
(AM_ERROR_CODE.BUSY after timeout)
|
Note: | SPI-speed is 250 MHz / clkdiv |
3.15 SPI: set clock-phase/-polarity
Set the SPI-clock-phase and -polarity.
The possible clock-phases and -polarities are:
- ADVABOARD_SPI_CLKCFG.IDLELOW_SHIFTFALLING_READRISING
- ADVABOARD_SPI_CLKCFG.IDLELOW_SHIFTRISING_READFALLING
- ADVABOARD_SPI_CLKCFG.IDLEHIGH_SHIFTRISING_READFALLING (default)
- ADVABOARD_SPI_CLKCFG.IDLEHIGH_SHIFTFALLING_READRISING
Usage: | void advaboard.spi_clkcfg(int clkcfg) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error
(AM_ERROR_CODE.BUSY after timeout)
|
SeeAlso: | ADVABOARD_SPI_CLKCFG |
3.16 SPI: set MUX
Set SPI-multiplexer of the AdvaBoard RPi1 (without locking!).
Usage: | void advaboard.spi_mux(int mux) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error |
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 advaboard.espi() instead.
Usage: | int[] advaboard.spi_comm(int[] txdata) |
---|---|
Parameters: |
|
Returns: | received bytes (array of 0..0xFF values) |
Throws: | AM_ERROR_Exception on error
(AM_ERROR_CODE.INVALID_ARGUMENT),
IllegalArgumentException for out-of-range parameters
|
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: | void advaboard.spi_lock() void advaboard.spi_lock(int timeout_ms) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error
(AM_ERROR_CODE.BUSY after timeout)
|
3.19 SPI: manually unlock
Unlock SPI again after advaboard.spi_lock(). This has to be used for every successful call to advaboard.spi_lock().
Usage: | void advaboard.spi_unlock() |
---|
3.20 SPI: set auto-locking-timeout
Set timeout, after which SPI-communication-functions throw AM_ERROR(AM_ERROR_CODE.BUSY) if they cannot lock the SPI.
Usage: | void advaboard.spi_locking_timeout(int timeout_ms) |
---|---|
Parameters: |
|
Throws: | IllegalArgumentException for out-of-range parameters |
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 advaboard.i2c() instead.
Usage: | int[] advaboard.rpii2c_comm(int address, int[] txdata, int rxlen) |
---|---|
Parameters: |
|
Returns: | received bytes (array of 0..0xFF values) |
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
3.22 I2C: set clock
Usage: | void advaboard.rpii2c_clk(int clkdiv) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error
(AM_ERROR_CODE.INVALID_ARGUMENT)
|
Note: | The I2C core clock is 250 MHz; default-clkdiv is 1500 (166.7kHz). (The Raspberry Pi datasheet is wrong, here.) |
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: | void advaboard.rpii2c_lock() void advaboard.rpii2c_lock(int timeout_ms) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error
(AM_ERROR_CODE.BUSY after timeout),
IllegalArgumentException for out-of-range parameters
|
3.24 I2C: manually unlock
Unlock I2C again after advaboard.i2c_lock(). This must be used for every successful call to advaboard.i2c_lock().
Usage: | void advaboard.rpii2c_unlock() |
---|
3.25 I2C: set auto-locking-timeout
Set timeout, after which I2C-communication-functions throw AM_ERROR(AM_ERROR_CODE.BUSY) if they cannot lock the I2C.
Usage: | void advaboard.rpii2c_locking_timeout(int timeout_ms) |
---|---|
Parameters: |
|
Throws: | IllegalArgumentException for out-of-range parameters |
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: | String[] advaboard.info() |
---|---|
Returns: | [model, rev, serno, f912_firmware, f353_firmware, cpld_firmware]
|
Throws: | AM_ERROR_Exception on error |
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: | float[] advaboard.temperature_read() |
---|---|
Returns: | [t_f912, t_f353]
|
Throws: | AM_ERROR_Exception on error |
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: | boolean done(int cmd) |
---|---|
Parameters: |
|
Returns: | True if done, False if not yet done |
Throws: | AM_ERROR_Exception on error |
Note: | This is only supported if the AdvaBoard RPi1-firmware is >= 20140219. For older firmware, AM_ERROR_CODE.NOT_IMPLEMENTED is thrown. |
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: | float[] advaboard.voltages_read() float[] advaboard.voltages_read(int select) |
---|---|
Parameters: |
|
Returns: | [v5v, vbatt, vdd_f912]
|
Throws: | AM_ERROR_Exception on error |
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: | void advaboard.power(int pwron, int cpld_3V, int peripheral_5V, int rpi, int tft, int tft_backlight) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error |
Note: |
|
SeeAlso: | event-based automation below |
4.3.3 power-on/off: read power-switches
Read the power-state.
Usage: | boolean[] advaboard.power_read() |
---|---|
Returns: | [pwron, cpld_3V, peripheral_5V, rpi, tft, tft_backlight]
|
Throws: | AM_ERROR_Exception on error |
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: | void advaboard.pins(int espi_rs485, int rpi, int tft) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error |
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: | boolean[] advaboard.pins_read() |
---|---|
Returns: | [espi_rs485, rpi, tft]
|
Throws: | AM_ERROR_Exception on error |
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: | void advaboard.power_tftblpwm(int pwm) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
4.3.7 TFT-backlight: read PWM
Read PWM of tft_backlight.
Usage: | int advaboard.power_tftblpwm_read() |
---|---|
Returns: | PWM-value (0..255) |
Throws: | AM_ERROR_Exception on error |
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 |
---|---|---|
1 | running | 0=stopped, 1=running |
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: | int advaboard.rtc_status() |
---|---|
Returns: | RTC-status (0..0xFF) |
Throws: | AM_ERROR_Exception on error |
SeeAlso: | ADVABOARD_RTC_STATUS, AdvaBoard RPi1 documentation |
4.4.2 control RTC
Control the RTC.
control may be one, or multiple or-combined values of:
- ADVABOARD_RTC_CONTROL.STOP
- ADVABOARD_RTC_CONTROL.START
- ADVABOARD_RTC_CONTROL.SET
- ADVABOARD_RTC_CONTROL.CLRFLAGS
- ADVABOARD_RTC_CONTROL.ALARM0_OFF
- ADVABOARD_RTC_CONTROL.ALARM0_ON
- ADVABOARD_RTC_CONTROL.ALARM1_OFF
- ADVABOARD_RTC_CONTROL.ALARM1_ON
Usage: | void advaboard.rtc_control(int control) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
SeeAlso: | ADVABOARD_RTC_CONTROL, AdvaBoard RPi1 documentation |
4.4.3 read RTC-time
Read the current RTC-time.
Usage: | long[] advaboard.rtc_read() |
---|---|
Returns: | [time, subseconds]
|
Throws: | AM_ERROR_Exception on error |
4.4.4 write RTC-time
Write time to a RTC register, but do not yet activate it. Use ADVABOARD_RTC_CONTROL.SET to actually set the RTC to the written time (or use advaboard.rtc_set()).
The initial time (at power-on) is 0x10000000. Do not set smaller times if you're using alarms.
Usage: | void advaboard.rtc_write(long time) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
4.4.5 set RTC-time
Set RTC (=write time to RTC-register and use ADVABOARD_RTC_CONTROL.SET).
The initial time (at power-on) is 0x10000000. Do not set smaller times if you're using alarms.
Usage: | void advaboard.rtc_set(long time) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
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:
- ADVABOARD_CONFIG_IO.INPUT: use as input
- ADVABOARD_CONFIG_IO.OUTPUT_OPENDRAIN: use as opendrain-output
- ADVABOARD_CONFIG_IO.OUTPUT: same as ADVABOARD_CONFIG_IO.OUTPUT_OPENDRAIN
- ADVABOARD_CONFIG_IO.OUTPUT_PUSHPULL: use as push-pull-output
Usage: | void advaboard.io0_config(int io4_ida0, int io5_ida1, int io6_pwm0, int io7_pwm1) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error |
SeeAlso: | ADVABOARD_CONFIG_IO, advaboard.analog_control() for IDA, advaboard.pwm_* for PWM |
4.5.2 I/O-configuration: read configuration of digital-I/Os 0.4..0.7
Read the I/O-configuration of I/Os 0.4..0.7.
Usage: | int[] advaboard.io0_config_read() int[] advaboard.io0_config_read(int select) |
---|---|
Parameters: |
|
Returns: | [io4_ida0, io5_ida1, io6_pwm0, io7_pwm1]
|
Throws: | AM_ERROR_Exception on error |
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:
- ADVABOARD_CONFIG_IO.INPUT: use as input
- ADVABOARD_CONFIG_IO.OUTPUT: use as output
Usage: | void advaboard.io1_config(int cpldio0, int cpldio1, int cpldio2, int cpldio3, int cpldio4, int cpldio5, int cpldio6, int cpldio7) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error |
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_GPIO.RPi_PWM, level) or by configuring the Raspberry Pi-PWM on P1-12 of the Raspberry Pi. |
SeeAlso: | ADVABOARD_CONFIG_IO |
4.5.4 I/O-configuration: read configuration of digital-I/Os 1.0..1.7
Read the I/O-configuration of the I/Os 1.0..1.7.
Usage: | int[] advaboard.io1_config_read() int[] advaboard.io1_config_read(int select) |
---|---|
Parameters: |
|
Returns: | [cpldio0, cpldio1, cpldio2, cpldio3, cpldio4, cpldio5, cpldio6, cpldio7]
|
Throws: | AM_ERROR_Exception on error |
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: | int[] advaboard.io_status(int len) |
---|---|
Parameters: |
|
Returns: | current status-bytes (array of 0..0xFF values) |
Throws: | AM_ERROR_Exception on error |
SeeAlso: | AdvaBoard RPi1 documentation |
4.5.6 digital-I/O: control digital-I/Os / events
Control the digital-I/Os of the AdvaBoard RPi1.
control may be one, or multiple or-combined values of:
- ADVABOARD_IO_CONTROL.CPLDINUPDATE_DISABLE
- ADVABOARD_IO_CONTROL.CPLDINUPDATE_ENABLE
- ADVABOARD_IO_CONTROL.EVENT0_DISABLE
- ADVABOARD_IO_CONTROL.EVENT0_ENABLE
- ADVABOARD_IO_CONTROL.EVENT1_DISABLE
- ADVABOARD_IO_CONTROL.EVENT1_ENABLE
- ADVABOARD_IO_CONTROL.EVENT2_DISABLE
- ADVABOARD_IO_CONTROL.EVENT2_ENABLE
- ADVABOARD_IO_CONTROL.EVENT3_DISABLE
- ADVABOARD_IO_CONTROL.EVENT3_ENABLE
Usage: | void advaboard.io_control(int control) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
SeeAlso: | ADVABOARD_IO_CONTROL, AdvaBoard RPi1 documentation |
4.5.7 digital-I/O: write outputs
Write digital-outputs.
Usage: | void advaboard.io_write(int io7654, int cpldio76543210) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error |
Note: |
|
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: | int advaboard.io_read1() |
---|---|
Returns: | digital-I/O-values (0..0xFF) |
Throws: | AM_ERROR_Exception on error |
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: | int[] advaboard.io_read2() |
---|---|
Returns: | digital-I/O-values (2 byte, each 0..0xFF) |
Throws: | AM_ERROR_Exception on error |
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: | void advaboard.io_set(int i) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
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: | void advaboard.io_clr(int i) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
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 a I/O-pin
Read the level of a digital-I/O-pin.
Usage: | boolean advaboard.io_get(int i) |
---|---|
Parameters: |
|
Returns: | true/1 if high, false/0 if low |
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
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: | int[] advaboard.analog_status(int len) |
---|---|
Parameters: |
|
Returns: | status-bytes (each 0..0xFF) |
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
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:
- ADVABOARD_ANALOG_CONTROL.ADC0_STOP
- ADVABOARD_ANALOG_CONTROL.ADC0_ONESHOT
- ADVABOARD_ANALOG_CONTROL.ADC0_CONTINUOUS
- ADVABOARD_ANALOG_CONTROL.ADC1_STOP
- ADVABOARD_ANALOG_CONTROL.ADC1_ONESHOT
- ADVABOARD_ANALOG_CONTROL.ADC1_CONTINUOUS
- ADVABOARD_ANALOG_CONTROL.ADC2_STOP
- ADVABOARD_ANALOG_CONTROL.ADC2_ONESHOT
- ADVABOARD_ANALOG_CONTROL.ADC2_CONTINUOUS
- ADVABOARD_ANALOG_CONTROL.ADC3_STOP
- ADVABOARD_ANALOG_CONTROL.ADC3_ONESHOT
- ADVABOARD_ANALOG_CONTROL.ADC3_CONTINUOUS
- ADVABOARD_ANALOG_CONTROL.ADC4_STOP
- ADVABOARD_ANALOG_CONTROL.ADC4_ONESHOT
- ADVABOARD_ANALOG_CONTROL.ADC4_CONTINUOUS
- ADVABOARD_ANALOG_CONTROL.IDA0_DISABLE
- ADVABOARD_ANALOG_CONTROL.IDA0_ENABLE
- ADVABOARD_ANALOG_CONTROL.IDA1_DISABLE
- ADVABOARD_ANALOG_CONTROL.IDA1_ENABLE
- ADVABOARD_ANALOG_CONTROL.PWM0_DISABLE
- ADVABOARD_ANALOG_CONTROL.PWM0_PWM8
- ADVABOARD_ANALOG_CONTROL.PWM0_PWM16
- ADVABOARD_ANALOG_CONTROL.PWM0_FREQ
- ADVABOARD_ANALOG_CONTROL.PWM1_DISABLE
- ADVABOARD_ANALOG_CONTROL.PWM1_PWM8
- ADVABOARD_ANALOG_CONTROL.PWM1_PWM16
- ADVABOARD_ANALOG_CONTROL.PWM1_FREQ
Usage: | void advaboard.analog_control(long control) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
SeeAlso: | ADVABOARD_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: | int[] advaboard.analogins_read() int[] advaboard.analogins_read(int select) |
---|---|
Parameters: |
|
Returns: | [ain0, ain1, ain2, ain3]
|
Throws: | AM_ERROR_Exception on error |
Note: | This only receives the last sampled values; you also have to use 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: | int advaboard.analogin_read(int i) |
---|---|
Parameters: |
|
Returns: | analog-value (0..65535) |
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
4.5.17 analog-I/O: write analog-outputs
Write analog-outputs of the AdvaBoard RPi1.
Usage: | void advaboard.analogouts_write(int ida0, int ida0_scale, int ida1, int ida1_scale) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
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: | int[] advaboard.analogouts_read() int[] advaboard.analogouts_read(int select) |
---|---|
Parameters: |
|
Returns: | [ida0, ida0_scale, ida1, ida1_scale]
|
Throws: | AM_ERROR_Exception on error |
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: | void advaboard.analogout_write(int i, int value, int scale) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
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: | int advaboard.analogout_read(int i) |
---|---|
Parameters: |
|
Returns: | analog-value (bit 0..7: value, bit 8..9: scale) |
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
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
Note that the clock has a tolerance of +-2%.
Usage: | void advaboard.pwm_clk(int clkdiv, int prescaler) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
4.5.22 PWM: read PWM-clock
Read the PWM-clock.
Usage: | int[] advaboard.pwm_clk_read() int[] advaboard.pwm_clk_read(int select) |
---|---|
Parameters: |
|
Returns: | [clkdiv, prescaler]
|
Throws: | AM_ERROR_Exception on error |
4.5.23 PWM: set PWM-value
Set a PWM.
Usage: | void advaboard.pwm_write(int i, int value) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
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: | int advaboard.pwm_read(int i) |
---|---|
Parameters: |
|
Returns: | PWM-value, 0x0000..0xffff |
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
4.5.25 PWM: read PWM-values
Read all PWM-values.
Usage: | int[] advaboard.pwms_read() int[] advaboard.pwms_read(int select) |
---|---|
Parameters: |
|
Returns: | [pwm0, pwm1]
|
Throws: | AM_ERROR_Exception on error |
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: | int advaboard.eventpwr_flags() |
---|---|
Returns: | event-handler-flags (0..0xFF) |
Throws: | AM_ERROR_Exception on error |
4.6.1.2 clear event-handler-flags
Clear some event-handler-flags.
Usage: | void advaboard.eventpwr_clear(int flags) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
4.6.1.3 trigger event-handler
Manually trigger an event-handler.
Usage: | void advaboard.eventpwr_trigger(int handler_pwr) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
4.6.1.4 handler: configure digital-outputs
Define which outputs should be set/cleared by an event-handler.
Usage: | void advaboard.eventpwr_output_write(int handler_pwr, int mask0, int output0) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
SeeAlso: | advaboard.eventpwr_power_write() |
4.6.1.5 handler: read digital-output-configuration
Read which outputs are set/cleared by an event-handler.
Usage: | int[] advaboard.eventpwr_output_read(int handler_pwr) |
---|---|
Parameters: |
|
Returns: | [mask0, output0]
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
SeeAlso: | advaboard.eventpwr_power_read() |
4.6.1.6 handler: configure analog-control
Define which analog-controls should be executed by an event-handler.
Usage: | void advaboard.eventpwr_analogcontrol_write(int handler_pwr, int analogcontrol0, int analogcontrol1, int analogcontrol2) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
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: | int[] advaboard.eventpwr_analogcontrol_read(int handler_pwr) |
---|---|
Parameters: |
|
Returns: | [analogcontrol0, analogcontrol1, analogcontrol2]
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
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: | void advaboard.eventpwr_power_write(int handler_pwr, int pwron, int cpld_3V, int peripheral_5V, int rpi, int tft, int tft_backlight) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
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: | int[] advaboard.eventpwr_power_read(int handler_pwr) |
---|---|
Parameters: |
|
Returns: | [pwron, cpld_3V, peripheral_5V, rpi, tft, tft_backlight]
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
4.6.1.10 event: define handler for I2C-interrupt
Define which handler should be executed when an I2C-interrupt occurs.
Usage: | void advaboard.eventpwr_i2cint_write(int handler_pwr_en) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
4.6.1.11 event: read handler for I2C-interrupt
Read which handler is executed when an I2C-interrupt occurs.
Usage: | int advaboard.eventpwr_i2cint_read() |
---|---|
Returns: | handler-number + 0x80 if the event is enabled |
Throws: | AM_ERROR_Exception on error |
4.6.1.12 event: define RTC-alarm
Define a RTC-alarm and which handler should be executed when the RTC-alarm occurs.
Usage: | void advaboard.rtc_alarm_write(int i, int handler_pwr, long time, long periodic) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
Note: |
|
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 advaboard_rtc.alarm_write() and advaboard.rtc_control().
Usage: | void advaboard.rtc_alarm_set(int i, int handler_pwr, long time, long periodic) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
SeeAlso: | advaboard.rtc_alarm_write(), advaboard.rtc_control() |
4.6.1.14 event: read RTC-alarm
Read RTC-alarm and which handler is executed when the RTC-alarm occurs.
Usage: | int[] advaboard.rtc_alarm_read(int i) |
---|---|
Parameters: |
|
Returns: | [handler_pwr, time, periodic]
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
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: | int advaboard.eventio_flags() |
---|---|
Returns: | handler-flags (0..0xFF) |
Throws: | AM_ERROR_Exception on error |
4.6.2.2 clear event-handler-flags
Clear some event-handler-flags.
Usage: | void advaboard.eventio_clear(int flags) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
4.6.2.3 trigger event-handler
Manually trigger an event-handler.
Usage: | void advaboard.eventio_trigger(int handler_io) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
4.6.2.4 handler: configure digital-outputs
Define which outputs should be set/cleared by an event-handler.
Usage: | void advaboard.eventio_output_write(int handler_io, int mask0, int output0, int mask1, int output1, int mask2, int output2) |
|||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Parameters: |
|
|||||||||||||||||||||
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
|||||||||||||||||||||
Note: | The F353-output-byte 2 is a virtual output, with:
|
|||||||||||||||||||||
SeeAlso: | AdvaBoard RPi1 documentation |
4.6.2.5 handler: read digital-output-configuration
Read which outputs are set/cleared by an event-handler.
Usage: | int[] advaboard.eventio_output_read(int handler_io) |
---|---|
Parameters: |
|
Returns: | [mask0, output0, mask1, output1, mask2, output2]
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
SeeAlso: | advaboard.eventio_output_write(), AdvaBoard RPi1 documentation |
4.6.2.6 handler: configure digital-control
Define which digital-controls should be executed by an event-handler.
Usage: | void advaboard.eventio_control_write(int handler_io, int control) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
SeeAlso: | AdvaBoard RPi1 documentation |
4.6.2.7 handler: read digital-control-configuration
Read which digital-controls are executed by an event-handler.
Usage: | int advaboard.eventio_control_read(int handler_io) |
---|---|
Parameters: |
|
Returns: | digital-control |
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
SeeAlso: | 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: | void advaboard.eventio_trigger_write(int event_io, int handler_io, int mask0, int input0, int mask1, int input1) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
4.6.2.9 event: read event-configuration
Read an event-configuration.
Usage: | int[] advaboard.eventio_event_read(int event_io) |
---|---|
Parameters: |
|
Returns: | [handler_io, mask0, input0, mask1, input1]
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
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: | void advaboard.f912_store() |
---|---|
Throws: | AM_ERROR_Exception on error |
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: | void advaboard.f353_store() |
---|---|
Throws: | AM_ERROR_Exception on error |
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: | int[] advaboard.espi(int sel, int[] txdata) |
---|---|
Parameters: |
|
Returns: | received bytes (array of 0..0xFF values) |
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
4.8.2 configure E-SPI-clock
Configure the E-SPI on the AdvaBoard RPi.
The valid clock-phases and -polarities are:
- ADVABOARD_SPI_CLKCFG.IDLELOW_SHIFTFALLING_READRISING
- ADVABOARD_SPI_CLKCFG.IDLELOW_SHIFTRISING_READFALLING
- ADVABOARD_SPI_CLKCFG.IDLEHIGH_SHIFTRISING_READFALLING (default)
- ADVABOARD_SPI_CLKCFG.IDLEHIGH_SHIFTFALLING_READRISING
Usage: | void advaboard.espi_clk(int clkdiv, int clkcfg) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error
(AM_ERROR_CODE.INVALID_ARGUMENT)
|
Note: |
|
SeeAlso: | ADVABOARD_SPI_CLKCFG |
4.8.3 E-SPI SEL0..3: set
Set E-SPI select-pins (incl. E-SPI-locking).
Usage: | void advaboard.espi_sel(int sel) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
4.8.4 E-SPI SEL0..3: read
Read E-SPI select-pins.
Usage: | int advaboard.espi_sel_read() |
---|---|
Returns: | E-SPI SEL0..3 value |
Throws: | AM_ERROR_Exception on error |
Note: | This returns the current levels, which may differ from the value set by 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: | boolean advaboard.espi_int_read() |
---|---|
Returns: | 0/false if no interrupt, >0/true on interrupt |
Throws: | AM_ERROR_Exception on error
(AM_ERROR_CODE.BUSY after timeout)
|
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: | void advaboard.espi_lock() void advaboard.espi_lock(int timeout_ms) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error
(AM_ERROR_CODE.BUSY after timeout)
|
4.8.7 manually unlock E-SPI
Unlock E-SPI again after advaboard.espi_lock(). This has to be used for every successful call to advaboard.espi_lock().
Usage: | void advaboard.espi_unlock() |
---|
4.8.8 set E-SPI auto-locking-timeout
Set timeout, after which E-SPI-communication-functions throw AM_ERROR(AM_ERROR_CODE.BUSY) if they cannot lock the E-SPI.
Usage: | void advaboard.espi_locking_timeout(int timeout_ms) |
---|---|
Parameters: |
|
Throws: | IllegalArgumentException for out-of-range parameters |
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: | int[] advaboard.i2c(int address, int[] txdata, int rxlen) |
---|---|
Parameters: |
|
Returns: | received bytes (array of 0..0xFF values) |
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
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:
int[] advaboard.i2c_prot(int address, int cmd) int[] advaboard.i2c_prot(int address, int cmd, int[] txdata)
Parameters: |
|
---|---|
Returns: | received bytes (array of 0..0xFF values) |
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
4.9.3 set I2C-clock
Set the I2C-clock.
Usage: | void advaboard.i2c_clk(int clkdiv) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error |
Note: | The I2C core clock is 250 MHz; default-clkdiv is 1500 (166.7kHz). (The Raspberry Pi datasheet is wrong, here.) |
4.9.4 read I2C-/SMBus-interrupt
Read the I2C-/SMBus-interrupt.
Usage: | boolean advaboard.i2c_int_read() |
---|---|
Returns: | 0/false if no interrupt, 1/true on interrupt |
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: | void advaboard.i2c_f912int_clear() |
---|---|
Throws: | AM_ERROR_Exception on error |
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: | void advaboard.i2c_lock() void advaboard.i2c_lock(int timeout_ms) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error
(AM_ERROR_CODE.BUSY after timeout)
|
4.9.7 manually unlock I2C
Unlock I2C again after advaboard.i2c_lock(). This must be used for every successful call to advaboard.i2c_lock().
Usage: | void advaboard.i2c_unlock() |
---|
4.9.8 set I2C auto-locking-timeout
Set timeout, after which I2C-communication-functions throw AM_ERROR(AM_ERROR_CODE.BUSY) if they cannot lock the I2C.
Usage: | void advaboard.i2c_locking_timeout(int timeout_ms) |
---|---|
Parameters: |
|
Throws: | IllegalArgumentException for out-of-range parameters |
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 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: | void advaboard.i2c_clkext(int delay) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
SeeAlso: | http://www.advamation.com/knowhow/raspberrypi/rpi-i2c-bug.html |
4.9.10 I2C-clock-stretching: read configured delay
Usage: | int[] advaboard.i2c_clkext_read() |
---|---|
Returns: | [delay, delay353]
|
Throws: | AM_ERROR_Exception on error |
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 advaboard.i2c_clkext().
The delay is injected in communications with I2C-devices where I2C_device_address & address_mask == address & address_mask.
Usage: | void advaboard.i2c_clkextinj(int addressmask, int address) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
Note: |
|
SeeAlso: | advaboard.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: | int[] advaboard.i2c_clkextinj_read() |
---|---|
Returns: | [addressmask, address] |
Throws: | AM_ERROR_Exception on error |
4.10 RS-232 / RS-485
4.10.1 configure RS-485 / RS-232
Configure the RS-485/RS-232 interface.
Usage: | void advaboard.rs485_cfg(int mux, int speed, int bit9) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error |
Note: |
|
4.10.2 read RS-485/RS-232 configuration
Read the RS-485/RS-232 configuration.
Usage: | int[] advaboard.rs485_cfg_read() |
---|---|
Returns: | [mux, speed, bit9]
|
Throws: | AM_ERROR_Exception on error |
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: | void advaboard.led(int mode) |
---|---|
Parameters: |
|
Throws: | AM_ERROR_Exception on error,
IllegalArgumentException for out-of-range parameters
|
SeeAlso: | AdvaBoard RPi1-documentation / Advamation RS-485-/I2C-protocol for blink-modes |