AdvaBoard RPi1 - Anleitung

1.1   Bestimmungsgemäße Verwendung

Das AdvaBoard RPi1 ist eine Erweiterungsplatine für den Raspberry Pi. Es handelt sich dabei um ein elektronisches Produkt, dessen Verwendung gewisses Fachwissen voraussetzt, und das deshalb nur von sachkundigen Personen eingesetzt werden darf.

Beim Anschluss anderer Geräte an das AdvaBoard RPi1 ist unbedingt darauf zu achten, dass diese zu den Spezifikationen (z.B. max. Spannungen, max. Ströme, Steckerbelegungen usw.) des AdvaBoard RPi1 passen, und die Hinweise zu den entsprechenden Schnittstellen beachtet werden. Insbesondere dürfen ohne Rücksprache mit uns an die RPi-Schnittstelle nur ein Raspberry Pi, und an die TFT-Display-Schnittstelle nur die von uns dafür vertriebenen Displays angeschlossen werden. Als Stromversorgung dürfen nur geregelte Netzteile mit 5V DC verwendet werden.

Lesen Sie vor der Benutzung diese Anleitung sowie die weitere Dokumentation sorgfältig durch, bewahren Sie sie auf und reichen Sie das Produkt nur zusammen mit dieser Anleitung an dritte Personen weiter.

1.2   Sicherheitshinweise

• Bei Schäden, die durch Nichtbeachten dieser Anleitung verursacht werden, erlischt die Gewährleistung/Garantie! Für Folgeschäden übernehmen wir keine Haftung!

  Bei Sach- oder Personenschäden, die durch unsachgemäße Handhabung oder Nichtbeachten der Sicherheitshinweise verursacht werden, übernehmen wir keine Haftung. In solchen Fällen erlischt die Gewährleistung/Garantie.

• Trotz sorgfältiger Arbeit kann leider nicht ausgeschlossen werden, dass das Produkt, die Software oder die Dokumentation Fehler enthält. Anwender sollten daher in jedem Fall überprüfen, ob das Produkt für ihre Anwendung geeignet ist und in ihrer Anwendung korrekt funktioniert.

  Für eventuelle Schäden, die durch fehlerhafte oder fehlende Information, Softwarefehler oder andere Fehler im Produkt verursacht werden, kann unabhängig von ihrer Ursache keine Haftung übernommen werden. Da wir zudem keinen Einfluss auf die Installation und Verwendung des Produkts haben, deckt die Gewährleistung nur das Produkt selbst ab.

• Das AdvaBoard RPi1 darf nicht für Anwendungen eingesetzt werden, bei denen eine Fehlfunktion oder ein Produktversagen zu Personenschäden, Tod, relevanten Sach- oder Umweltschäden oder anderen schwerwiegenden Folgeschäden führen kann.

  Soll das AdvaBoard RPi dennoch für einen derartigen Zweck verwendet (oder in ein anderes derartiges Produkt eingebaut) werden, so ist sicherzustellen, dass durch eine Fehlfunktion oder ein Produktversagen unseres Produkts keine derartigen Schäden auftreten können!

• Das AdvaBoard RPi1 ist ein elektronisches Produkt. Es darf deshalb nur von fachkundigen Personen eingesetzt werden, da bei unsachgemäßer Verwendung Schäden am Produkt und evtl. an damit verbundenen Geräten auftreten können. Es ist zudem stets auf entsprechenden ESD-Schutz zu achten.
• Das Produkt darf nicht extremen Temperaturen, starken Temperaturschwankungen, direktem Sonnenlicht, starken Erschütterungen, Feuchtigkeit, Nässe, Dämpfen, Schmutz, brennbaren Gasen oder übermäßiger mechanischer Beanspruchung ausgesetzt werden.
• Das Produkt darf nicht bzw. nur nach Rücksprache verndert oder umgebaut werden.
• Das Produkt ist kein Spielzeug und sollte außerhalb der Reichweite von Kindern aufbewahrt werden! Das Produkt und dessen Zubehör kann zudem verschluckbare Kleinteile beinhalten; bewahren Sie diese Teile unbedingt außerhalb der Reichweite von Kindern auf. Lassen Sie ebenso niemals Verpackungsmaterial unachtsam herumliegen, da insbesondere Plastikfolien für Kinder zu einem gefährlichen Spielzeug werden können. Es besteht Erstickungsgefahr!
• Wenn anzunehmen ist, dass ein gefahrloser Betrieb nicht mehr möglich ist, so ist das Produkt außer Betrieb zu setzen und gegen unbeabsichtigten Betrieb zu sichern. Dies ist insbesondere dann der Fall, wenn das Produkt sichtbare Beschädigungen aufweist.
• Sollten Sie Zweifel oder Fragen zum korrekten Gebrauch des Produkts oder bezüglich der Sicherheit haben, so wenden Sie sich bitte an uns oder an qualifiziertes Fachpersonal.

4.1   Hardware

Maße:

• Platinengröße: ca. 96.6mm × 64.8mm
• 2 Befestigungsbohrungen für den Raspberry Pi Rev. 2, Durchmesser 3.15mm
• 4 Befestigungsbohrungen in den 4 Ecken, Durchmesser 3.15mm, Abstand 85.4mm × 59.0mm
• weitere Maße: siehe Maßzeichnung (PDF)

Steckverbinder:

Beschriftung	Beschreibung
+5V	5V-Netzteil-Anschluss
I2C	I2C-Schnittstelle
ANALOG-/DIGITAL-I/O	Analog- und Digital-I/Os
E-SPI	erweiterte SPI-Schnittstelle
DISPLAY	TFT-Display-Schnittstelle
RPi	Raspberry Pi-Anbindung
RS232 TTL	RS-232-Schnittstelle mit TTL-Pegeln
RS485	RS-485-Schnittstelle
BATT	3V-Batterie-Anschluss
Masse-Anschluss	zusätzlicher, niederohmiger Masse-Anschluss

Die Details zu den einzelnen Steckverbindern finden Sie in den entsprechenden Abschnitten dieser Anleitung.

Jumper / Steckbrücken:

• RPi5V: Raspberry Pi-Stromversorgungs-Jumper
  Dieser Jumper verbindet die AdvaBoard RPi1-Stromversorgung mit der Raspberry Pi-Stromversorgung, und überbrückt damit den Power-Schalter für den Raspberry Pi.

  Er muss immer gesteckt sein, wenn das AdvaBoard RPi1 vom Raspberry Pi mit Strom versorgt wird!

  Er sollte nicht gesteckt sein, wenn das AdvaBoard RPi1 den Raspberry Pi mit Strom versorgt, und das AdvaBoard den Raspberry Pi ein-/ausschalten soll.

  Zudem kann er verwendet werden, um bei fehlerhafter Power-Management-Konfiguration den Raspberry Pi wieder mit Strom zu versorgen, um dann über den Raspberry Pi die Konfiguration korrigieren zu können.

  geschlossen	Raspberry Pi-Stromversorgung und AdvaBoard-Stromversorgung verbunden
  offen	Raspberry Pi-Stromversorgung von AdvaBoard-Stromversorgung getrennt (=Raspberry Pi-Stromversorgung vom AdvaBoard aus schaltbar)

• TERM: RS-485-Terminator

  Position	Bedeutung
  links / entfernt	RS-485-Terminator deaktiviert
  rechts / "1"	RS-485-Terminator aktiviert

• PROGRAMMER: JTAG-/C2-Schnittstelle / Firmware-Update
  Dieser Jumper ist nur für Firmware-Updates des AdvaBoard RPi1 notwendig. Im normalen Betrieb muss er sich entweder in der Aufbewahrungsposition befinden, oder komplett vom AdvaBoard RPi entfernt sein.

  Wird das TFT70-Display auf das AdvaBoard RPi1 gesteckt, so sollte dieser Jumper entfernt (und separat aufbewahrt) werden, da er sonst mit dem Display kollidiert.

  Position	Bedeutung
  links / entfernt	Aufbewahrung
  mitte / "PROC"	Firmware-Update Mikrocontroller
  rechts / "CPLD"	Firmware-Update CPLD

Seriennummer:

Auf der Rückseite des AdvaBoard RPi1 befindet sich auf einem gelben Aufkleber die Seriennummer des AdvaBoard RPi1.

Das AdvaBoard RPi1, die TFT-Displays, der Raspberry Pi usw. enthalten höchst empfindliche IC-Chips. Um die Platinen und andere Komponenten vor Beschädigung durch statische Elektrizität (ESD) zu schützen, sollten Sie bei allen Arbeiten am AdvaBoard RPi1, TFT-Display, Raspberry Pi usw. einige Vorsichtsmaßnahmen beachten:

• Trennen Sie alle Komponenten vom Stromnetz, bevor Sie eine Komponente an- oder abstecken.
• Achten Sie auf entsprechenden ESD-Schutz, bevor Sie mit elektronischen Bauteilen arbeiten. Hierzu sollte ein geerdetes Schutzarmband angelegt werden.
• Fassen Sie die Platinen nur an den Rändern an, und berühren Sie möglichst nicht die IC-Chips und die Anschlüsse.
• Verwenden Sie immer eine stabile, antistatische, nichtleitende Unterlage für die Platinen.

4.2   Montage

AdvaBoard RPi1 Befestigungslöcher und Befestigungsset

Das AdvaBoard RPi1 besitzt 6 Montagelöcher:

• 4 Löcher an den Ecken, z.B.
  • zur Montage des AdvaBoards in einem Gehäuse oder auf einer Grundplatte
  • zur direkten Befestigung des TFT32-Displays
  • zur Befestigung anderer Displays mittels Adapter, bzw. zur Befestigung an einem TFT-Display-Einbaurahmen
  • zur Befestigung eines Raspberry Pi B+/A+ (mittels Adapter)
• 2 Löcher passend zum Raspberry Pi-Modell B bzw. A, um einen Raspberry Pi B Rev. 2 (bzw. A) am AdvaBoard RPi1 zu befestigen

Die Löcher besitzen einen Durchmesser von ca. 3.1mm, die genauen Positionen können der Maßzeichnung entnommen werden. Zur Befestigung sollten M3 Kunststoffschrauben bzw. Kunststoff-Abstandsbolzen verwendet werden. Werden stattdessen Metallschrauben verwendet, so müssen jeweils über und unter der Platine zusätzliche Kunststoff-Beilagscheiben verwendet werden, um Kurzschlüsse und Beschädigungen der Platinen zu verhindern.
Zudem ist auf ausreichende Abstände bzw. ausreichende Isolation zwischen dem AdvaBoard RPi1, dem Raspberry Pi, einem evtl. Gehäuse usw. zu achten, um Kurzschlüsse zu vermeiden.

Das AdvaBoard RPi1 kann sowohl an den Raspberry Pi-Modellen B und A, als auch (mit zusätzlichem Befestigungskit) an den neueren Modellen B+ und A+ befestigt werden.

Raspberry Pi B und AdvaBoard RPi1	Raspberry Pi B+ und AdvaBoard RPi1
(zum Vergrößern anklicken)	(zum Vergrößern anklicken)

4.2.1   Montage eines Raspberry Pi B / A

Um einen Raspberry Pi B (bzw. A) am AdvaBoard RPi1 zu befestigen, wird folgendes Material benötigt (siehe Foto):

• AdvaBoard RPi1
• Raspberry Pi B Rev. 2 (bzw. A)
• Flachbandkabel 26-polig, 3.5cm
• aus dem AdvaBoard RPi1-Zubehörset:
  • 2 Kunststoff-Abstandsbolzen M3, Länge 18mm
  • 2 Kunststoff-Schrauben**, M3, Länge 6mm
  • 2 Kunststoff-Muttern**, M3

Montage: erforderliches Material

Zur Montage sind folgende Schritte notwendig (siehe Fotos):

1. Abstandsbolzen in die Löcher des AdvaBoard RPi1 stecken und mit Muttern fixieren.
2. Kabel am Raspberry Pi anstecken.
3. Kunststoff-Schrauben durch die Löcher des Raspberry Pi stecken.
4. Raspberry Pi so auf die Abstandsbolzen legen, dass die Schrauben in die Abstandsbolzen greifen; Raspberry Pi festschrauben.
5. Kabel am AdvaBoard RPi1 anstecken.

Schritt 1 + 2: Abstandsbolzen befestigen, Kabel anstecken

Schritt 3 + 4: Kunststoffschrauben einstecken und anziehen

Schritt 5: Kabel anstecken

AdvaBoard RPi1 mit montiertem Raspberry Pi B

4.2.2   Montage eines Raspberry Pi B+ / A+

Um einem Raspberry Pi B+ (bzw. A+) am AdvaBoard RPi1 zu befestigen, wird folgendes Material benötigt (siehe Foto):

• AdvaBoard RPi1
• Raspberry Pi B+ (bzw. A+)
• Flachbandkabel 40-polig auf 26-polig, 8cm
• zusätzliches Befestigungskit:
  • 1 Adapterplatte
  • 4 Kunststoffschrauben M3, 8mm
  • 8 Kunststoffmuttern M3
  • 4 Kunststoffschrauben M2.5
  • 4 Kunststoff-Abstandshalter

Mit den M3-Schrauben wird das AdvaBoard RPi1 an der Adapterplatte befestigt, mit den M2.5-Schrauben der Raspberry Pi B+ bzw. A+.

Montage: erforderliches Material

Folgende Schritte sind notwendig (siehe Fotos):

1. M3-Schrauben von oben in die 4 Eck-Löcher des AdvaBoard RPi1 stecken und jeweils 1 Mutter aufschrauben. Die Muttern dienen im Folgenden als Abstandshalter.

   Soll am AdvaBoard RPi1 zudem ein 3.2"-TFT-Display befestigt werden, so müssen statt der M3-Schrauben die 12mm-Abstandsbolzen aus dem Zubehörset verwendet werden.

   Soll das AdvaBoard RPi1 an einem TFT-Einbaurahmen befestigt werden, so müssen die Muttern weggelassen, und stattdessen Kunststoffscheiben und die TFT*_MOUNT-Alu-Winkel aufgesteckt werden. Genauere Informationen hierzu finden sich in der TFT-Display-Einbaurahmen-Anleitung

2. Adapterplatte auf diese Schrauben legen. Hierbei auf die Ausrichtung der Adapterplatte achten (siehe Foto).

3. Adapterplatte mit 4 M3-Muttern am AdvaBoard RPi1 befestigen.

4. Raspberry Pi B+ (bzw. A+) auf die Adapterplatte legen, und nacheinander mit den M2.5-Schrauben und den Abstandshaltern an der Adapterplatte festschrauben (siehe Foto).

5. Kabel am Raspberry Pi und danach am AdvaBoard RPi1 anstecken.

Schritt 1: M3-Schrauben + Muttern am AdvaBoard RPi1 befestigen

Schritt 2 + 3: Adapterplatte am AdvaBoard RPi1 befestigen

Schritt 4: Raspberry Pi an der Adapterplatte befestigen

Schritt 5: Kabel anstecken

AdvaBoard RPi1 mit montiertem Raspberry Pi B+

4.2.3   Montage eines TFT-Displays

Das 3.2"-TFT-Display (TFT32) kann mit den Abstandsbolzen (12mm) des AdvaBoard RPi1-Zubehörsets direkt auf das AdvaBoard RPi1 aufgeschraubt werden. Hierzu werden die 4 12mm-Abstandsbolzen zunächst an den Ecken des AdvaBoard RPi1 befestigt, dann das TFT32-Display auf das AdvaBoard RPi1 aufgesteckt und anschließend verschraubt.

Raspberry Pi B + AdvaBoard RPi1	Raspberry Pi B + AdvaBoard RPi1 + TFT32-Display

Das AdvaBoard RPi1 kann ebenfalls mit entsprechenden Halterungen an anderen Displays bzw. TFT-Display-Einbaurahmen befestigt werden. Weitere Informationen hierzu finden sich in der TFT-Display-Einbaurahmen-Anleitung.

4.3   Raspberry Pi-Anschluss

Das AdvaBoard RPi1 wird mit einem 26-poligen Flachbandkabel an den Raspberry Pi angeschlossen. Dieses Kabel dient sowohl der Daten- als auch der Stromübertragung zwischen Raspberry Pi und AdvaBoard RPi1.

Dieses Kabel sollte aus technischen Gründen möglichst kurz gehalten werden.

Raspberry Pi-Modelle B+ und A+:

Es wird ein Flachbandkabel mit einem 40-poligen und einem 26-poligen Steckverbinder verwendet. Der 40-polig Steckverbinder muss hierbei am Raspberry Pi, und der 26-polige Steckverbinder am AdvaBoard RPi1 angesteckt werden (siehe Foto). Pin 1 des Kabels (rot markiert) muss zum Rand des Raspberry Pi zeigen.

Die Standard-Kabellängen betragen hierbei:

• 8cm, falls das AdvaBoard RPi1 auf den Raspberry Pi B+/A+ montiert werden soll
• 12cm, falls das AdvaBoard RPi1 direkt neben den Raspberry Pi B+/A+ montiert werden soll

Verbindung zwischen Raspberry Pi B+ und AdvaBoard RPi1

Raspberry Pi-Modelle B und A:

Die Standard-Kabellängen betragen hierbei:

• 3.5cm, falls das AdvaBoard RPi1 auf den Raspberry Pi B/A montiert werden soll
• 12cm, falls das AdvaBoard RPi1 direkt neben den Raspberry Pi B/A montiert werden soll

Hier wird ein 26-poliges Flachbandkabel mit zwei etwas unterschiedlichen Enden genutzt:

• Auf der einen Seite besitzt der Flachkabelstecker einen zusätzlichen "Bügel" als Zugentlastung; diese Seite sollte ans AdvaBoard RPi1 angeschlossen werden.
• Der Flachkabelstecker der anderen Seite besitzt keine Zugentlastung (da sonst der Stecker zu hoch wäre, um das AdvaBoard RPi1 auf dem Raspberry Pi zu montieren). Diese Seite sollte an den Raspberry Pi angeschlossen werden. Hierbei ist unbedingt auf richtige Polung zu achten! (Pin 1 zur Platinenaußenseite, "Nase" zur Platineninnenseite, siehe Bild)

Flachbandkabel-Enden: für Raspbery Pi (links), für AdvaBoard RPi1 (rechts)

Verbindung zwischen Raspberry Pi und AdvaBoard RPi1

Stromversorgung:

Zusätzlich muss das AdvaBoard RPi1 mit Strom versorgt werden. Informationen hierzu finden Sie weiter unten im Abschnitt Stromversorgung.

4.4   Software-Überblick

Zum Betrieb des AdvaBoard RPi1 am Raspberry Pi ist ein funktionsfähiges Linux-System auf dem Raspberry Pi erforderlich. Wir empfehlen hierbei Raspbian, jedoch sollte auch jedes andere auf dem Raspberry Pi funktionsfähige Linux-System mit dem AdvaBoard RPi1 funktionieren. Aktuelle Linux-Systeme für den Raspberry Pi, sowie Installationsanleitungen, erhalten Sie auf den Raspberry Pi-Webseiten.

Zusätzlich muss die AdvaBoard RPi-Software auf dem System installiert werden. Diese Software stellen wir für einige Systeme bereits vorkompiliert in Binärform, sowie zusätzlich als Quellcode zur Verfügung. Die notwendigen Informationen zur Installation finden Sie in der Readme-Datei der Software.

Alternativ können Sie von uns SD-Karten mit fertig installiertem Linux-System (Raspbian) und installierter und konfigurierter AdvaBoard RPi1-Software beziehen.

Weitere Informationen finden Sie im nachfolgenden Abschnitt Software

7.1   AdvaBoard-GUI

Die "AdvaBoard-GUI" ist eine grafische Benutzeroberfläche, mit der auf die meisten Funktionen des AdvaBoard RPi1 auf einfache Art und Weise zugegriffen werden kann. Dabei kann diese Benutzeroberfläche:

• entweder direkt auf dem Raspberry Pi laufen
• oder auf einem PC laufen, der dann mittels JSON-RPC über das Netzwerk mit dem Rasbperry Pi kommuniziert.

Weitere Informationen hierzu finden Sie in der Software-Dokumentation.

Screenshots des Programms:

(zum Vergrößern anklicken)

7.2   am_rpi_advaboard_tool

Neben den Programmbibliotheken sind die Kommandozeilenprogramme ein wichtiger Bestandteil der Software. Diese Kommandozeilenprogramme enthalten nahezu die komplette Funktionalität der entsprechenden Bibliotheken, und sind einfach zu verwenden.

Es wird daher empfohlen, die Funktionen des AdvaBoard RPi1 zuerst mit dem Kommandozeilenprogramm am_rpi_advaboard_tool auszuprobieren, und sie erst danach in eigene (C-/Java-/Python-)Programme einzubauen. Da die Funktionsnamen und Parameter des Kommandozeilenprogramms nahezu identisch mit den Bibliotheksfunktionen sind, können die Kommandozeilenaufrufe später einfach in C-/Java-/Python-Funktionsaufrufe überführt werden.

Ebenfalls wird empfohlen, AdvaBoard-Funktionen, die im eigenen Programm nicht wie erwartet funktionieren, mit dem Kommandozeilenprogramm zu testen.

Diese Vorgehensweise kann zu deutlichen Zeiteinsparungen führen und die Fehlersuche deutlich erleichtern, da hiermit das AdvaBoard RPi1 und der eigene Programmcode getrennt getestet werden können.

Die Kommandozeilenprogramme sind darüber hinaus geeignet, um das AdvaBoard RPi1 in Shell-Skripten zu verwenden.

Eine Übersicht über die Funktionen erhalten Sie per am_rpi_advaboard_tool --help:

Usage:
  am_rpi_advaboard_tool [OPTION...] - AdvaBoard RPi1 commandline-interface

Help Options:
  -h, --help                         Show help options

Application Options:
  -m, --mode=MODE parameters ...
   Generic modes:
     INIT                    - init the AdvaBoard RPi1

     INFO                    - print system information
     LED        0x00..0xFF   - set LED
     TEMPERATURE             - get temperature of microcontrollers

   Power modes:
     VOLTAGES                - get voltages
     POWER      PART ONOFF   - power-on/off
     POWER_READ              - read power-on/off
     PINS       PINS EN      - enable/disable pins
     PINS_READ               - read pin-enable/disable
     TFTBL_PWM  0x00..0xFF   - set PWM for TFT_BACKLIGHT
     TFTBL_PWM_READ          - get PWM of  TFT_BACKLIGHT
         PART:  PWR, CPLD_3V, PERIPHERAL_5V, RPI, TFT, TFT_BACKLIGHT
         ONOFF: ON, 1, OFF, 0
         PINS:  ESPI, RPI, TFT
         EN:    ENABLE, 1, DISABLE, 0

         Note: TFT_BACKLIGHT is only used by 3.2" and 7.0" TFT display.
               TFTBL_PWM can be used to control the brightness of 3.2" TFT,
               and should be 0xFF for 7.0" TFT.

   RTC modes:
     RTC_STATUS                         - read RTC-status
     RTC_CONTROL CONTROL ...            - control RTC
     RTC_READ                           - read RTC-time
     RTC_SET     TIME                   - set RTC-time
         CONTROL: 8-bit control value, or one or more of:
                  RTC_STOP, RTC_START,
                  RTC_SET,
                  RTC_CLRFLAGS,
                  RTC_ALARM0_OFF, RTC_ALARM0_ON,
                  RTC_ALARM1_OFF, RTC_ALARM1_ON
         TIME:    time in 32-bit seconds (usually since epoch)
                  Do not set to < 0x10000000 if you use alarms.

   Power-/RTC-automatization modes:
     EVENTPWR_FLAGS                         - read  event-handler-flags
     EVENTPWR_CLEAR          FLAGS          - clear event-handler-flags
     EVENTPWR_TRIGGER        h_pwr          - trigger event-handler
     EVENTPWR_POWER_WRITE    h_pwr PWRON CPLD_3V PERIPHERAL_5V RPi TFT TFT_BL
                                            - configure power-on/off @ handler
     EVENTPWR_POWER_READ     h_pwr          - read      power-on/off @ handler
     EVENTPWR_OUTPUT_WRITE   h_pwr MASK0 OUTPUT0 - configure outputs @ handler
     EVENTPWR_OUTPUT_READ    h_pwr               - read      outputs @ handler
     EVENTPWR_ANALOGCONTROL_WRITE h_pwrr CONTROL0 CONTROL1 CONTROL2
                                            - configure analog-control @ handler
     EVENTPWR_ANALOGCONTROL_READ  h_pwr     - read      analog-control @ handler
        FLAGS: flag-bitmask to clear, 0x00..0xff
        h_pwr: power-event-handler number, 0..7
               0 is reset event-handler
               1 is switch-to-battery-handler event-handler
               2 is power-supply-switched-on event-handler
        PWRON CPLD_3V PERIPHERAL_5V RPi TFT TFT_BL:
               0=power-on, 1=power-off, -1=don't change
        MASK0:   bitmask for outputs, 0=do not set this bit, 1=set this bit
        OUTPUT0: output-value, 0=low, 1=high
        CONTROL0..2: control-bits

     EVENTPWR_I2CINT_WRITE  h_pwr_en         - configure I2C-interrupt-event
     EVENTPWR_I2CINT_READ                    - read      I2C-interrupt-event
     RTC_ALARM_SET          i h_pwr TIME [PERIODIC] - set+enable RTC-alarm
     RTC_ALARM_READ         i                - read RTC-alarm-configuration
        h_pwr:    handler to trigger, 0..7
        h_pwr_en: like h_pwr, but highest bit (0x80) enables the event
        i:        RTC-alarm number, 0/1
        TIME:     alarm-time, if < 0x10000000 it is relative to now
        PERIODIC: periodiciy of the alarm, 0=non-periodic alarm

   Digital-/Analog-I/O modes:
     IO_CONFIG         IOCFG [CPLDIOCFG] - config digital-I/Os
     IO_CONFIG_READ                      - read digital-I/O-configuration
     IO_STATUS                           - read digital-status
     IO_CONTROL        CONTROL ...       - control digital-I/Os
     IO_WRITE          OUTPUT0 [OUTPUT1] - write I/Os
     IO_READ                             - read  I/Os
     IO_SET            i                 - set   I/O to high
     IO_CLR            i                 - clear I/O to low
         IOCFG:     i|o|p * 4 (or 0/-1=don't change)
                    i=input, o=opendrain-output, p=pushpull-output
         CPLDIOCFG: i|o   * 8 (or 0/-1=don't change)
                    i=input, o=output
         CONTROL:   16-bit control-value, or one or more of:
                    CPLDINUPDATE_DISABLE, CPLDINUPDATE_ENABLE
                    EVENT0_DISABLE, EVENT0_ENABLE
                    EVENT1_DISABLE, EVENT1_ENABLE
                    EVENT2_DISABLE, EVENT2_ENABLE
                    EVENT3_DISABLE, EVENT3_ENABLE
         i:         I/O-number (0x04..0x07, 0x10..0x17)
         OUTPUT0/1: I/O-values (0x00..0xff, -1=don't change)

     ANALOG_STATUS                      - read  analog-status
     ANALOG_CONTROL    CONTROL ...      - control analog-I/Os / PWM
     ANALOGIN_READ     [i]              - read  analog-input(s)
     ANALOGOUT_WRITE   i VALUE SCALE    - write analog-I/Os
     ANALOGOUT_READ    [i]              - read  analog-output(s)
     PWM_CONTROL       PWMCONTROL ...   - control PWM
     PWM_CLK           CLKDIV PRESCALER - set PWM-speed
     PWM_CLK_READ                       - get PWM-speed
     PWM_WRITE         i VALUE          - write PWM
     PWM_READ          [i]              - read  PWM
         CONTROL:   32-bit control-value, or one or more of:
                    ADC0_STOP, ADC0_ONESHOT, ADC0_CONTINUOUS,
                    ADC1_STOP, ADC1_ONESHOT, ADC1_CONTINUOUS,
                    ADC2_STOP, ADC2_ONESHOT, ADC2_CONTINUOUS,
                    ADC3_STOP, ADC3_ONESHOT, ADC3_CONTINUOUS,
                    ADC4_STOP, ADC4_ONESHOT, ADC4_CONTINUOUS,
                    IDA0_DISABLE, IDA0_ENABLE,
                    IDA1_DISABLE, IDA1_ENABLE
         PWMCONTROL: 8-bit control-value, or one or more of:
                     PWM0_DISABLE, PWM0_PWM8, PWM0_PWM16, PWM0_FREQ
                     PWM1_DISABLE, PWM1_PWM8, PWM1_PWM16, PWM1_FREQ
         i:         analog-in-number (0..3) or PWM-number (0..1)
         VALUE:     16-bit value for PWM / 8-bit value for IDA
         SCALE:     scale for IDA, 0=0..0.25mA, 1=0..0.5mA, 2=0..1mA, 3=0..2mA
         CLKDIV:    clock-divider 1..256
         PRESCALER: clock-prescaler 1,4,12,48

         PWM-speed:
             - PWM8:  repeating-frequency = 95.7kHz  / CLKDIV / PRESCALER
             - PWM16: repeating-frequency = 373.84Hz / CLKDIV / PRESCALER
             - FREQ:  frequency = 12.25MHz / CLKDIV / PRESCALER / VALUE
             - the speed can differ +- 2%
         PWM-value:
             - 0x0000 is 100% high, 0xFFFF is nearly 100% low,
               to get 100% low, use IO_CLR on the pin
             - PWM8,FREQ only use the higher byte of VALUE
             - FREQ: value is time of the low-/high-phase,
               0x01 is highest frequency, 0xff is nearly lowest freq.,
               0x00 (interpreted as 0x100) is lowest freq.

   I/O-automatization modes:
     EVENTIO_FLAGS                              - read  event-handler-flags
     EVENTIO_CLEAR          FLAGS               - clear event-handler-flags
     EVENTIO_TRIGGER        h_io                - trigger event-handler
     EVENTIO_OUTPUT_WRITE   h_io MASK0 OUTPUT0 [MASK1 OUTPUT1 [MASK2 OUTPUT2]]
                                                - configure outputs @ handler
     EVENTIO_OUTPUT_READ    h_io                - read      outputs @ handler
     EVENTIO_CONTROL_WRITE  h_io CONTROL        - configure control @ handler
     EVENTIO_CONTROL_READ   h_io                - read      control @ handler
        FLAGS: flag-bitmask to clear, 0x00..0x0f
        h_io:  I/O-event-handler number, 0..3, 0 is reset-handler
        MASK0:   bitmask for outputs, 0=skip this bit, 1=set this bit
        OUTPUT0: output-value, 0=low, 1=high
        CONTROL: control-bits (16 bit)

     EVENTIO_EVENT_WRITE  i h_io MASK0 INPUT0 MASK1 INPUT1 - configure event
     EVENTIO_EVENT_READ   i                                - read event
        i:         event-number, 0..3
        evio:      event-handler to trigger, 0..3
        MASK0..1:  bitmask for inputs, 0=skip this bit, 1=use this bit
        INPUT0..1: input-match-value, 0=low, 1=high

   Configuration-storage/EEPROM modes:
     EEPROM_F912_STORE      - store configuration of F912 (power, RTC) to EEPROM
     EEPROM_F353_STORE      - store configuration of F353 (I/O) to EEPROM

   E-SPI modes:
    ESPI          SEL TXDATA... - communicate with SPI-device
    ESPI_CLK      CLKDIV [CLKCFG]          - set  E-SPI clock
    ESPI_SEL      SEL                      - set  E-SPI SEL0..3
    ESPI_SEL_READ                          - read E-SPI SEL0..3
    ESPI_INT_READ                           - read SPI-interrupt
         MUX:    0=E-SPI, 1=TFT, 2=TP, 3=SD, -1=don't change
         SEL:    SEL0..3 values (0x00..0x0F), -1=don't change
         CLKDIV: SPI-clock-divisor (4/8/16/.../65536), -1=don't change,
                 clock=250MHz/CLKDIV
         CLKCFG: 0: idle low,  shift at falling-edge, read at rising-edge
                 1: idle low,  shift at rising-edge, read at falling-edge
                 2: idle high, shift at rising-edge, read at falling-ege (*)
                 3: idle high, shift at falling-edge, read at rising-edge
                 (*) default: 2
         TXDATA: bytes to transmit

   I2C modes:
     I2C         RXLEN ADDR TXDATA... - communicate with I2C-device
     I2C_PROT    ADDR CMD TXDATA...   - communicate wit I2C-devices
                                            with the Advamation-protocol
            RXLEN:  number of bytes to receive
            ADDR:   I2C-device-address, 0x00..0x7F
            TXDATA: bytes to transmit

     I2C_CLK       CLK             - set I2C-clock
     I2C_INT_READ                  - read I2C-interrupt-pin
     I2C_F912INT_CLEAR             - clear F912-I2C-interrupt / set int-pin
            CLK:    clock-divider 2/4/8...65536, I2C-clk = 250MHz/CLK, or
                    5/10/20/50/100/200/300/400kHz

     I2C_CLKEXT     DELAY          - configure I2C-clock-stretching
     I2C_CLKEXT_READ               - read I2C-clock-stretching-configuration
     I2C_CLKEXTINJ  MASK ADDR      - configure I2C-clock-stretching-injection
     I2C_CLKEXTINJ_READ            - read I2C-clock-stretching-injection conf.
            DELAY:  clock-stretching-delay in the I2C-read-ACK-phase
                    delay=DELAY*1.306?s, e.g. DELAY=8 for 100kHz
            MASK,ADDR: address and mask for clock-stretching-injection; only
                inject clock-stretching if ADDR & MASK == DEVICEADDR & MASK
                e.g. 0xFF 0xFF to disable, 0x00 0x00 to enable for all addresses

   RS-485 modes:
     RS485_CFG     MUX [SPEED [BIT9]]  - configure RS-232/RS-485
     RS485_CFG_READ                    - read RS-232/RS-485-configuration
         MUX:   RS485,0,RS232,1
         SPEED: 0..0xffff, value = 196 000 000/baudrate
         BIT9:  0,1

   low-level modes:
     F912        RXLEN CMD TXDATA...      - communicate with F912
     F353        RXLEN CMD TXDATA...      - communicate with F353
     CPLDREG     TXDATA                   - write CPLD-registers
     GPIO_WRITE  GPIOs LEVEL              - write Raspberry Pi GPIOs
     GPIO_READ   GPIOs                    - read  Raspberry Pi GPIOs
     SPI_CLK     CLKDIV                   - set SPI-clock
     SPI_CLKCFG  CLKCFG                   - set SPI-clock-configuration
     SPI_MUX     MUX                      - set SPI-MUX
     SPI_COMM    TXDATA...                - communicate over SPI
     RPiI2C_CLK  CLKDIV                   - set RPi-I2C-clock
     RPiI2C_COMM RXLEN ADDR TXDATA...     - communicate over SPI

   Notes:
     Note that all clocks/timings may differ by +-2%.

     All parameters are case-insensitive.
     All numeric parameters can be decimal, hexadecimal (0x...) or
     binary (0b...) numbers.
     If you want to use "-1" as parameter, prepend it with "--" to make
     sure that it's not interpreted as an option, e.g.
     ... -m EVENTPWR_POWER_WRITE 1 -- -1 -1 -1 1 -1 -1

  -l, --nolock                       don't use locking (use with care!)
  -v, --verbose=LEVEL                verbosity level (default: 64)
      (DEBUG: 128, INFO: 64, MESSAGE: 32, WARNING: 16, CRITICAL: 8, ERROR: 4/0)

Da die Funktionen des AdvaBoard RPi1 recht umfangreich sind, enthält auch das Kommandozeilenprogramm sehr viele Funktionen. Die wichtigsten Funktionen bzw. Kommandozeilenprogramm-Aufrufe finden Sie jedoch nochmal in den jeweiligen Abschnitten dieser Anleitung. Details zu den einzelnen Funktionen finden Sie in der Software-Dokumentation.

Die wichtigsten Parameter sind:

--help

Gibt eine Hilfemeldung bzw. eine Übersicht über die möglichen Parameter aus.

-m MODE

Wählt eine bestimmte Funktion aus.

-v

Stellt die Ausführlichkeit der Programmausgaben ein.

128 / DEBUG:

Zusätzlich zu "INFO" werden weitere Informationen ausgegeben (z.B. alle angegebenen Parameter in geparster Form), die für Debugging-Zwecke nützlich sein könnten.

64 / INFO (Standardeinstellung):

Gibt die Informationen in menschenlesbarer Form aus. Diese Einstellung wird für die interaktive Verwendung empfohlen.
Es wird davon abgeraten, diese Ausgaben z.B. per Skript zu parsen.

32 / MESSAGE:

Wie "INFO", jedoch v.a. ohne die Angabe des Autors, der Programmversion usw.

16 / WARNING:

Ausgabe in kurzer, parsbarer Form. Alle redundanten Informationen und Informationen, die die Lesbarkeit erleichtern, werden weggelassen.

8 / CRITICAL, 4 / ERROR:

Wie 16 / WARNING, jedoch evtl. Unterdrückung von Warnungen.

Beispiel:

• sudo am_rpi_advaboard_tool -m RTC_STATUS:

  Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)
  
  RTC-status: 0x02
  running: YES
  error:   none
  alarm0:  off, no alarm
  alarm1:  off, no alarm
  OK.
  

• sudo am_rpi_advaboard_tool -m RTC_STATUS -v 32:

  RTC-status: 0x02
  running: YES
  error:   none
  alarm0:  off, no alarm
  alarm1:  off, no alarm
  OK.
  

• sudo am_rpi_advaboard_tool -m RTC_STATUS -v 16:

  0x02
  

Ist der am_rpi_advaboard_tool-Aufruf erfolgreich, so wird ein Exit-Code von 0 zurückgegeben. Bei Verbosity-Einstellungen (-v) von 32 oder höher besteht die letzte ausgegebene Zeile zudem aus OK.
Im Fehlerfall wird eine Fehlermeldung ausgegeben und ein entsprechender Fehlercode zurückgeliefert, z.B:

$ am_rpi_advaboard_tool -m INFO
Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)

ERROR: Permission denied. (-13)
$ echo $?
243

8.1   Stromversorgung

Das AdvaBoard RPi1 kann auf zwei Arten mit Strom versorgt werden:

1. vom Raspberry Pi: Am Micro-USB-Anschluss des Raspberry Pi wird ein Netzteil angeschlossen. Der Raspberry Pi versorgt dann das AdvaBoard RPi1 über das 26-polige Flachbandkabel.

   In diesem Fall muss der Jumper "RPi5V" auf dem AdvaBoard RPi1 gesetzt sein!

2. vom 5V-Netzteil-Anschluss: Am Netzteil-Anschluss des AdvaBoard RPi1 wird ein 5V-Netzteil angeschlossen. Das AdvaBoard RPi1 versorgt dann den Raspberry Pi über das 26-polige Flachbandkabel.

   In diesem Fall kann das AdvaBoard RPi1 den Raspberry Pi – z.B. abhängig von bestimmten Ereignissen – ein- und ausschalten, sofern der Jumper "RPi5V" nicht gesetzt ist. Zudem kann das AdvaBoard RPi1 das 5V-Netzteil selbst ein- bzw. ausschalten, sofern das Netzteil dies unterstützt (siehe PWRON-Steuersignal), und dann in einen sehr stromsparenden Modus wechseln.

Wichtig: Es darf gleichzeitig immer nur eine der beiden Versorgungen (5V-Netzteil am AdvaBoard oder Netzteil am Raspberry Pi) angeschlossen sein, niemals beide!

5V-Netzteil-Steckverbinder: Printstecker, 3-polig, RM 2.54mm

5V-Netzteil-Einbaustecker	Netzteil-Kabel
(Ansicht: Steckseite)

8.2   Batterie

Falls das Netzteil des AdvaBoard RPi1 bzw. Raspberry Pi ausgeschaltet oder vom Stromnetz getrennt ist, kann die Echtzeituhr und der Power-Management-Controller von einer Batterie versorgt werden. Darüber hinaus steht die Batteriespannung auf dem I²C-Steckverbinder zur Verfügung.

Damit ist es möglich, dass:

• die Echtzeituhr auch bei ausgeschaltetem Netzteil weiterläuft, und
• bei Verwendung eines vom AdvaBoard RPi1 ein-/ausschaltbaren Netzteils (siehe PWRON-Steuersignal) das Netzteil zu bestimmten Uhrzeiten, auf Tastendruck oder durch ein spezielles externes I²C-Gerät wieder eingeschaltet werden kann. Bei leerer Batterie wird zudem automatisch das Netzteil eingeschaltet.

Die Batteriespannung sollte etwa 3V betragen, Spannungen über 3.4V sind nicht zulässig. Die Echtzeituhr und der Power-Management-Controller funktionieren bereits ab ca. 1.8V, das Ausschalten des Netzteils (siehe PWRON-Steuersignal) dürfte jedoch abhängig vom verwendeten Netzteil eine höhere Spannung benötigen.

Batterie-Steckverbinder: Printstecker, 2-polig, RM 2.54mm

Batterie-Einbaustecker	Batterie-Kabel
(Ansicht: Steckseite)

8.3   Initialisierung

Bevor das AdvaBoard RPi1 vom Raspberry Pi angesprochen werden kann, müssen zuerst der Raspberry Pi und das AdvaBoard RPi1 initialisiert werden.

Kommandozeilenprogramm:

sudo am_rpi_advaboard_tool -m init

C-Funktion (Dokumentation):

am_rpi_advaboard_init(SPICLK)

8.4   Systeminformationen

Die Revision, Seriennummer, und Firmware-Versionen des AdvaBoard RPi1 ist im AdvaBoard hinterlegt und kann abgefragt werden.

Kommandozeilenprogramm:

sudo am_rpi_advaboard_tool -m info

z.B:

$ sudo am_rpi_advaboard_tool -m info
Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)

Model:         AdvaBoard RPi1
Revision:      1
Serial:        11160fffff
F353-firmware: 20131028
F912-firmware: 20131028
OK.

C-Funktion (Dokumentation):

am_rpi_advaboard_info(...)

8.5   LED

Das AdvaBoard RPi1 enthält eine grüne LED. Diese leuchtet im Normalfall, sobald eine Stromversorgung (per Netzteil-Steckverbinder oder Raspberry Pi) an das AdvaBoard RPi1 angeschlossen wird.

Es ist jedoch möglich, die LED auszuschalten oder (in verschiedenen Frequenzen) blinken zu lassen. Dies kann v.a. zu Diagnosezwecken hilfreich sein, z.B. indem man den Blinkcode ändert, um die Kommunikation zwischen dem Raspberry Pi und dem AdvaBoard RPi1 zu überprüfen.

Kommandozeilenprogramm:

sudo am_rpi_advaboard_tool -m LED 0x00..0xFF

C-Funktion (Dokumentation):

am_rpi_advaboard_led(BLINKCODE)

LED-Blinkcodes:

Code	Beschreibung
0x00	aus
0x01	blinken, ca. 3.13 Hz
0x02	blinken, ca. 1.56 Hz
0x04	blinken, ca. 0.78 Hz
0x08	blinken, ca. 0.39 Hz
0xff	an
weitere	siehe led_blinkcodes.pdf

8.6   Power-Management

Das AdvaBoard RPi1 besitzt ein integriertes Power-Management, mit dem der Strom zu bestimmten Teilen und Schnittstellen zeit- und ereignisgesteuert ein- und ausgeschaltet werden kann. Dies kann zu deutlichen Stromeinsparungen führen, was insbesondere für batteriebetriebene Anwendungen (z.B. autarke Anwendungen mit einem Solarmodul) interessant ist.

sudo am_rpi_advaboard_tool -m POWER PWR|CPLD_3V|PERIPHERAL_5V|RPI|TFT|TFT_BACKLIGHT ON|OFF
sudo am_rpi_advaboard_tool -m POWER_READ

$ sudo am_rpi_advaboard_tool -m POWER_READ
Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)

PWR_ON:        ON
CPLD_3V:       ON
PERIPHERAL_5V: off
RPi:           ON
TFT:           off
TFT_BACKLIGHT: off
OK.

am_rpi_advaboard_power(...)
am_rpi_advaboard_power_read(...)

sudo am_rpi_advaboard_tool -m PINS ESPI|RPI|TFT ENABLE|DISABLE
sudo am_rpi_advaboard_tool -m PINS_READ

$ sudo am_rpi_advaboard_tool -m PINS_READ
Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)

E-SPI/RS-485: disabled
RPi:          ENABLED
TFT:          disabled
OK.

am_rpi_advaboard_pins(...)
am_rpi_advaboard_pins_read(...)

sudo am_rpi_advaboard_tool -m VOLTAGES

$ sudo am_rpi_advaboard_tool -m VOLTAGES
Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)

V_5V:   4.93 V (should be ~5V)
V_Batt: 2.80 V (should be ~3V, if battery is connected)
VCC:    2.97 V (should be ~3V)
OK.

am_rpi_advaboard_voltages_read(...)

8.7   Echtzeituhr

Der Raspberry Pi enthält selbst leider keine Echtzeituhr, so dass bei jedem Booten üblicherweise Uhrzeit und Datum manuell eingegeben oder über das Netzwerk (per NTP) bezogen werden müssen.

Das AdvaBoard RPi1 behebt dieses Problem, indem es dem Raspberry Pi eine (batteriegepufferte) Echtzeituhr ("Real Time Clock", RTC) zur Verfügung stellt. Zudem kann die Echtzeituhr verwendet werden, um den Raspberry Pi und das AdvaBoard RPi1 zu bestimmten Uhrzeiten oder in bestimmten Intervallen einzuschalten oder bestimmte Aktionen auszulösen.

Die Echtzeituhr besteht aus:

• einem 32-Bit-Sekundenzähler, plus 15 Bit Nachkommastellen
• 2 einstellbaren Alarmen:
  • zu einem bestimmten Zeitpunkt (z.B. "am 1.1.2014 um 12:34:56") oder
    relativ zur aktuellen Zeit (z.B. "in 1 Minute")
  • einmalig, oder periodisch alle 1..16777215 Sekunden (=maximal alle ca. 194 Tage)
• Batteriepufferung (falls eine Batterie angeschlossen ist)

Der Sekundenzähler der Echtzeituhr sollte dabei üblicherweise als Sekunden seit 01.01.1970 (Epoche der Unixzeit) interpretiert werden, was eine einfache Handhabung mit Standard-Uhrzeitfunktionen ermöglicht.

Der Initialwert der Echtzeituhr beträgt 0x10000000 (ca. 04.07.1978); alle Alarmzeitpunkte, die kleiner als dieser Wert sind, werden als Alarme relativ zur aktuellen Uhrzeit interpretiert. Weitere Informationen zu den Alarmen finden Sie im Abschnitt Ereignisgesteuerte Automatisierung.

Kommandozeilenprogramm:

sudo am_rpi_advaboard_tool -m RTC_STATUS
sudo am_rpi_advaboard_tool -m RTC_CONTROL control ...
sudo am_rpi_advaboard_tool -m RTC_READ
sudo am_rpi_advaboard_tool -m RTC_SET time
sudo am_rpi_advaboard_tool -m RTC_ALARM_SET i evpwr time
sudo am_rpi_advaboard_tool -m RTC_ALARM_READ i
sudo am_rpi_advaboard_tool -m EVENTPWR_*

z.B.:

• Echtzeituhr abfragen und setzen:

  $ sudo am_rpi_advaboard_tool -m RTC_STATUS
  Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)
  
  RTC-status: 0x02
  running: YES
  error:   none
  alarm0:  off, no alarm
  alarm1:  off, no alarm
  OK.
  
  $ sudo am_rpi_advaboard_tool -m RTC_READ
  Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)
  
  RTC: 268438825.1432
  OK.
  
  $ sudo am_rpi_advaboard_tool -m RTC_SET `date "+%s"`
  Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)
  
  OK.
  
  $ sudo am_rpi_advaboard_tool -m RTC_READ
  Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)
  
  RTC: 1390256716.0421
  OK.
  
  $ sudo am_rpi_advaboard_tool -v 16 -m RTC_READ
  1390256718.0421
  

• Echtzeituhrzeit abfragen und in Datum umwandeln:

  $ date -d "@`sudo am_rpi_advaboard_tool -v 16 -m RTC_READ`"
  Mon Jan 20 23:34:55 CET 2014
  

• Echtzeituhr auf aktuelle Sytemuhrzeit setzen:

  $ sudo am_rpi_advaboard_tool -v 32 -m RTC_SET `date "+%s"`
  OK.
  

• Systemuhrzeit auf Echtzeituhr-Zeit setzen:

  $ sudo date -s "@`sudo am_rpi_advaboard_tool -v 16 -m RTC_READ`"
  Mon Jan 20 23:35:46 CET 2014
  

• Echtzeituhr-Alarm (Alarm 0) in 10 Sekunden:

  $ sudo am_rpi_advaboard_tool -m RTC_ALARM_SET 0 1 10
  Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)
  
  OK.
  
  $ sudo am_rpi_advaboard_tool -m RTC_STATUS
  Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)
  
  RTC-status: 0x12
  running: YES
  error:   none
  alarm0:  ON,  no alarm
  alarm1:  off, no alarm
  OK.
  
  $ sudo am_rpi_advaboard_tool -m RTC_ALARM_READ 0
  Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)
  
  RTC-alarm 0: event 1 at 1390256849s
  OK.
  
  # 10 seconds later...
  $ sudo am_rpi_advaboard_tool -m RTC_STATUS
  Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)
  
  RTC-status: 0x32
  running: YES
  error:   none
  alarm0:  ON,  ALARM occurred
  alarm1:  off, no alarm
  OK.
  

C-Funktionen (RTC-Dokumentation, Alarm-Dokumentation):

am_rpi_advaboard_rtc_status(...)
am_rpi_advaboard_rtc_control(...)
am_rpi_advaboard_rtc_read(...)
am_rpi_advaboard_rtc_write(...)
am_rpi_advaboard_rtc_set(...)

am_rpi_advaboard_rtc_alarm_write(...)
am_rpi_advaboard_rtc_alarm_set(...)
am_rpi_advaboard_rtc_alarm_read(...)

am_rpi_advaboard_eventpwr_*(...)

8.8   Digital-/Analog-I/O

Das AdvaBoard bietet einige Analog- und Digital-I/Os:

• 4 Analog-Eingänge (16 Bit, standardmäßig 50 Samples/s) inkl. Spannungsteiler und Filter
• 2 Analog-Ausgänge (8 Bit, einstellbarer Bereich 0..0.25/0.5/1.0/2.0mA, max. 2.0V),
  alternativ als Digital-I/Os nutzbar
• 2 Digital-I/Os per Mikrocontroller inkl. PWM
• 8 Digital-I/Os per CPLD
  mit optionaler hardwareunterstützter Verarbeitung (z.B. für 2-Phasen-Counter)

Alle Digital-I/Os verwenden einen 3.3V Pegel und sind 5V-tolerant. Die I/Os können zudem in der Ereignisgesteuerte Automatisierung verwendet werden.

Im Auslieferungszustand sind alle I/Os als Eingänge konfiguriert.

Sollten für eine Anwendung mehr I/Os notwendig sein, so können per I²C, E-SPI oder RS-485 externe I/O-Platinen an das AdvaBoard angeschlossen werden.

Steckverbinder: Wannenstecker, 20-polig, RM 2.54mm

I/O-Einbaustecker

(Ansicht: Steckseite)

sudo am_rpi_advaboard_tool -m ANALOG_CONTROL control ...
# control:
#   ADC0_STOP, ADC0_ONESHOT, ADC0_CONTINUOUS,
#   ADC1_STOP, ADC1_ONESHOT, ADC1_CONTINUOUS,
#   ADC2_STOP, ADC2_ONESHOT, ADC2_CONTINUOUS,
#   ADC3_STOP, ADC3_ONESHOT, ADC3_CONTINUOUS,
#   ADC4_STOP, ADC4_ONESHOT, ADC4_CONTINUOUS

sudo am_rpi_advaboard_tool -m ANALOG_STATUS

sudo am_rpi_advaboard_tool -m ANALOGIN_READ [0..4]

am_rpi_advaboard_analog_status(...)
am_rpi_advaboard_analog_control(...)
am_rpi_advaboard_analogins_read(...)
am_rpi_advaboard_analogin_read(...)

sudo am_rpi_advaboard_tool -m ANALOG_CONTROL control ...
# control:
#   IDA0_DISABLE, IDA0_ENABLE,
#   IDA1_DISABLE, IDA1_ENABLE
sudo am_rpi_advaboard_tool -m ANALOG_STATUS
sudo am_rpi_advaboard_tool -m ANALOGOUT_WRITE [0..1] value scale
sudo am_rpi_advaboard_tool -m ANALOGOUT_READ  [0..1]

am_rpi_advaboard_analog_status(...)
am_rpi_advaboard_analog_control(...)
am_rpi_advaboard_analogouts_write(...)
am_rpi_advaboard_analogouts_read(...)
am_rpi_advaboard_analogout_write(...)
am_rpi_advaboard_analogout_read(...)

sudo am_rpi_advaboard_tool -m PWM_CONTROL control ...
# control:
#   PWM0_DISABLE, PWM0_PWM8, PWM0_PWM16, PWM0_FREQ,
#   PWM1_DISABLE, PWM1_PWM8, PWM1_PWM16, PWM1_FREQ
sudo am_rpi_advaboard_tool -m ANALOG_STATUS

sudo am_rpi_advaboard_tool -m PWM_CLK clkdiv prescaler
sudo am_rpi_advaboard_tool -m PWM_CLK_READ

sudo am_rpi_advaboard_tool -m PWM_WRITE i value
sudo am_rpi_advaboard_tool -m PWM_READ [0..1]

am_rpi_advaboard_analog_status(...)
am_rpi_advaboard_analog_control(...)
am_rpi_advaboard_pwm_clk(...)
am_rpi_advaboard_pwm_clk_read(...)
am_rpi_advaboard_pwm_write(...)
am_rpi_advaboard_pwm_read(...)
am_rpi_advaboard_pwms_read(...)

sudo am_rpi_advaboard_tool -m IO_CONFIG iocfg [cpldiocfg]
# iocfg:     4* i|o|p, bzw. -1 (=keine Änderung)
# cpldiocfg: 8* i|o,   bzw. -1 (=keine Änderung)
sudo am_rpi_advaboard_tool -m IO_CONFIG_READ

sudo am_rpi_advaboard_tool -m IO_WRITE output0 [output1]
sudo am_rpi_advaboard_tool -m IO_READ
sudo am_rpi_advaboard_tool -m IO_SET iobit
sudo am_rpi_advaboard_tool -m IO_CLR iobit

am_rpi_advaboard_io0_config(...)
am_rpi_advaboard_io0_config_read(...)
am_rpi_advaboard_io_write(...)
am_rpi_advaboard_io_read1(...)
am_rpi_advaboard_io_read2(...)
am_rpi_advaboard_io_set(...)
am_rpi_advaboard_io_clr(...)
am_rpi_advaboard_io_get(...)

8.9   E-SPI

Die SPI-Schnittstelle bietet einen einfachen und sehr schnellen seriellen Datenbus. Sie eignet sich insbesondere für Peripherie, die eine hohe Datenrate oder kurze Latenzzeiten benötigt, z.B. externe CPLDs/FPGAs, Displays usw.

Der SPI auf dem AdvaBoard RPi1 ist um mehrere Adressleitungen und einen Interrupt erweitert, und wird deshalb zur besseren Unterscheidung "E-SPI" genannt.

Das AdvaBoard verwendet dabei:

• 5V Versorgungsspannung
• 3.3V Pegel, 5V-tolerant
• einstellbaren Takt zwischen 3.81kHz und 62.5 MHz
• 4 zusätzliche Adressleitungen (SEL0..3)
• einen optionalen Interrupt

Die zusätzliche Adressleitungen können entweder als normale Chip-Select-Leitungen verwendet werden, um insgesamt 4 SPI-Geräte anzusprechen, oder mit zusätzlichen Adressdekodern bis zu 16 Geräte adressieren. Damit ist der "E-SPI" ideal geeignet, um auf einfache Art und Weise per Flachbandkabel bis zu 16 externe Platinen an das AdvaBoard anzuschließen.

Steckverbinder: Wannenstecker, 10-polig, RM 2.54mm

E-SPI-Einbaustecker

(Ansicht: Steckseite)

Kommandozeilenprogramm:

sudo am_rpi_advaboard_tool -m ESPI     sel txdata...
# sel: 0x00..0x0F / 0..15

sudo am_rpi_advaboard_tool -m ESPI_CLK clkdiv [clkcfg]
# clkdiv: SPI-Frequenzteiler (4/8/16/.../65536), SPI-Takt = 250MHz/clkdiv
# clkcfg: 0: Ruhezustand low,  Shift bei fallender  Flanke, Lesen bei steigender Flanke
#         1: Ruhezustand low,  Shift bei steigender Flanke, Lesen bei fallender Flanke
#         2: Ruhezustand high, Shift bei steigender Flanke, Lesen bei fallender Flanke (Standard)
#         3: Ruhezustand high, Shift bei fallender  Flanke, Lesen bei steigender Flanke

sudo am_rpi_advaboard_tool -m ESPI_SEL sel
#  sel: 0x00..0x0F / 0..15
sudo am_rpi_advaboard_tool -m ESPI_SEL_READ

sudo am_rpi_advaboard_tool -m ESPI_INT_READ

z.B.:

• E-SPI-Adressleitungen setzen: SEL0 und SEL1 high, SEL2 und SEL3 low (=Adresse 3):

  $ sudo am_rpi_advaboard_tool -m ESPI_SEL 0b0011
  Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)
  
  OK.
  

• E-SPI-Adressleitungen lesen:

  $ sudo am_rpi_advaboard_tool -m ESPI_SEL_READ
  Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)
  
  E-SPI SEL: 0x03 / 3
  SEL0: 1
  SEL1: 1
  SEL2: 0
  SEL3: 0
  OK.
  

• E-SPI-Kommunikation mit E-SPI-Adresse 5:

  $ sudo am_rpi_advaboard_tool -m ESPI 5 0x12 0x34
  Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)
  
  -> 0x12 0x34
  <- 0xff 0xff
  OK.
  

C-Funktionen (Dokumentation):

am_rpi_advaboard_espi(...)
am_rpi_advaboard_espi_clk(...)
am_rpi_advaboard_espi_sel(...)
am_rpi_advaboard_espi_sel_read(...)

sudo am_rpi_advaboard_tool -m ESPI_INT_READ

am_rpi_advaboard_espi_int_read(...)

8.10   I²C / SMBus

Der I²C-Bus [7] ist mittlerweile die Schnittstelle für digitale Sensoren, z.B. für Temperatursensoren, Temperatur-/Feuchtesensoren, Beschleunigungssensoren, Bewegungsmelder etc.

Das AdvaBoard RPi1 verwendet dabei:

• 3.3V Versorgungsspannung, max. 100mA
• 3.3V Pegel (nicht 5V-tolerant!)
• eine separate Leitung für die Versorgung per Batterie
• eine Interrupt-Leitung für schnelle Reaktionszeiten und das Aufwecken des AdvaBoards/Raspberry Pis bei bestimmten Ereignissen (ähnlich SMBus #ALERT)
• einen optionalen CRC (SMBus PEC)

Die Steckerbelegung wurde dabei so gewählt, dass das Übersprechen zwischen SDA, SCL und der Interrupt-Leitung möglichst gering ist.

Die Stromaufnahme aller angschlossenen 3.3V-Geräte darf 100mA nicht überschreiten. Die I²C-Adressen 8 und 9 sind durch das AdvaBoard RPi1 bereits belegt und können nicht für externe I²C-Sensoren bzw. -Geräte verwendet werden.

Steckverbinder: Wannenstecker, 6-polig, RM 2.54mm

I2C-Einbaustecker

(Ansicht: Steckseite)

Kommandozeilenprogramm:

sudo am_rpi_advaboard_tool -m I2C      rxlen addr txdata...

sudo am_rpi_advaboard_tool -m I2C_CLK  clk
# clk: I2C-Frequenzteiler 2/4/8...65536, I2C-Takt = 250MHz/clk
#      bzw. 5/10/20/50/100/200/300/400kHz

z.B.:

• I2C-Takt auf 100 kHz setzen:

  $ sudo am_rpi_advaboard_tool -m I2C_CLK 100kHz
  Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)
  
  OK.
  

• per I2C (mit dem I/O-Controller) kommunizieren:

  $ sudo am_rpi_advaboard_tool -m I2C 7  9  1 0x10
  Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)
  
  -> ADR 0x09 DATA 0x01 0x10
  <- 0x05 0x11 0x16 0x02 0x33 0x16 0x09
  OK.
  

C-Funktionen (Dokumentation):

am_rpi_advaboard_i2c(...)
am_rpi_advaboard_i2c_clk(...)

am_crc_smbus(...)

sudo am_rpi_advaboard_tool -m I2C_INT_READ
sudo am_rpi_advaboard_tool -m I2C_F912INT_CLEAR

am_rpi_advaboard_i2c_int_read(...)
am_rpi_advaboard_i2c_f912int_clear(...)

sudo am_rpi_advaboard_tool -m I2C_CLKEXT delay
# delay: min. Delay-Zeit in 1.306ms, z.B. 8 für >= 100kHz
sudo am_rpi_advaboard_tool -m I2C_CLKEXT_READ

sudo am_rpi_advaboard_tool -m I2C_CLKEXTINJ mask addr
# mask, addr: Clock-Stretching nur anpassen, falls
#   mask & addr == Geräteadresse & mask, z.B.
#   0xFF 0xFF = deaktiviert,
#   0x00 0x00 = für alle Adressen aktiviert
sudo am_rpi_advaboard_tool -m I2C_CLKEXTINJ_READ

sudo am_rpi_advaboard_tool -m I2C_PROT addr cmd txdata...

am_rpi_advaboard_i2c_prot(...)

8.11   RS-485 / RS-232

Das AdvaBoard RPi1 enthält eine RS-485- und eine RS-232-TTL-Schnittstelle, die beide an die RS-232-Schnittstelle des Raspberry Pi angebunden sind, sowie einen Umschalter zwischen diesen Schnittstellen.

Kommandozeilenprogramm:

sudo am_rpi_advaboard_tool -m RS485_CFG RS485|RS232
sudo am_rpi_advaboard_tool -m RS485_CFG_READ

z.B.:

• RS-232-TTL-Schnittstelle auswählen:

  $ sudo am_rpi_advaboard_tool -m RS485_CFG RS232
  Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)
  
  OK.
  

• RS-485-Schnittstelle auswählen:

  $ sudo am_rpi_advaboard_tool -m RS485_CFG RS485
  Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)
  
  OK.
  

• Konfiguration zurücklesen:

  $ sudo am_rpi_advaboard_tool -m RS485_CFG_READ
  Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)
  
  interface: RS-485
  speed:     0x06a5, for baudrate ~115226
  bit9-inj.: ENABLED
  OK.
  

C-Funktionen (Dokumentation):

am_rpi_advaboard_rs485_cfg(...)
am_rpi_advaboard_rs485_cfg_read(...)

8.11.1   RS-485 / EIA-485

Die RS-485-Schnittstelle ist eine störfeste Industrieschnittstelle, an die als Bus (evtl. mittels Hubs) mehrere Geräte angeschlossen werden können, und die auch für die Überbrückung langer Distanzen geeignet ist.

Das AdvaBoard enthält eine RS-485-Schnittstelle mit automatischer Richtungsumschaltung, einen RS-485-Leitungs-Terminator, sowie eine optionale automatische 9.Bit-Modifikation.

• Terminator: RS-485-Leitungs-Terminator, per Steckbrücke ("TERM") aktivierbar/deaktivierbar
  (Widerstand 680 Ω, 120 Ω, 680 Ω)
• automatische Richtungsumschaltung: Die RS-485-Kommunikationsrichtung wird mit Hilfe eines Timeouts automatisch umgeschaltet. Der Timeout wird hierbei aus der einstellbaren Kommunikationsgeschwindigkeit errechnet.
• 9.Bit-Modifikation: Für die Kommunikation mit einigen Mikrocontrollern und Geräten (und auch für das Advamation RS-485-Protokoll) wird das 9. Bit einer Kommunikations als "Adressmarker" verwendet. Das AdvaBoard RPi1 kann diese Modifikation des 9. Bits automatisch vornehmen. Das Parity-Bit der seriellen Schnittstelle des Raspberry Pi muss dann auf "space parity" eingestellt sein.

Da die RS-485-Schnittstelle mit der RS-232-Schnittstelle des Raspberry Pi verbunden ist, kann die RS-485-Schnittstelle exakt genauso wie eine normale RS-232-Schnittstellen angesprochen werden (z.B. per minicom bzw. das /dev/ttyAMA0-Device des Raspberry Pi).

Steckverbinder: Printstecker, 4-polig, RM 2.54mm

RS-485-Einbaustecker	RS-485-Kabel
(Ansicht: Steckseite)

Pin	Signal	Farbe [8]	Beschreibung
1	+12V/NC		nicht verbunden
2	RS-N	braun	RS-485 im Ruhezustand negativere Leitung (ca. 2V gegen GND)
3	RS-P	orange	RS-485 im Ruhezustand positivere Leitung (ca. 3V gegen GND)
4	GND	schwarz	Masse

[8]	Aderfarbe im RS-485-Kabel des AdvaBoard RPi1-Zubehörsets

Kommandozeilenprogramm:

sudo am_rpi_advaboard_tool -m RS485_CFG RS485|RS232 speed bit9
# speed: 0..0xFFFF, speed = 196 000 000 / baudrate
# bit9:  0=keine 9.Bit-Modification, 1=9.Bit-Modification aktivieren
sudo am_rpi_advaboard_tool -m RS485_CFG_READ

z.B.:

• RS-485 auswählen, Geschwindigkeit (für die automatische Richtungsumschaltung) auf 9600 kbps setzen, 9.Bit-Modifikation deaktivieren:

  $ sudo am_rpi_advaboard_tool -m RS485_CFG RS485 20417 0
  Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)
  
  OK.
  

• RS-485-Konfiguration lesen:

  $ sudo am_rpi_advaboard_tool -m RS485_CFG_READ
  Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)
  
  interface: RS-485
  speed:     0x4fc1, for baudrate ~9599
  bit9-inj.: DISABLED
  OK.
  

• RS-485 auswählen, Geschwindigkeit (für die automatische Richtungsumschaltung) auf 115200 kbps setzen, 9.Bit-Modifikation aktivieren (=Standardeinstellung im Auslieferungszustand):

  $ sudo am_rpi_advaboard_tool -m RS485_CFG RS485 1701 1
  Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)
  
  OK.
  

• RS-485-Konfiguration lesen:

  $ sudo am_rpi_advaboard_tool -m RS485_CFG_READ
  Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)
  
  interface: RS-485
  speed:     0x06a5, for baudrate ~115226
  bit9-inj.: ENABLED
  OK.
  

8.11.3   RS-232 TTL

An die integrierte RS-232-Schnittstelle mit TTL-Pegeln kann verschiedene Peripherie, z.B. ein GPS- oder Funkmodul, angeschlossen werden.

Zudem ist ein Pegelwandler verfügbar, der diese Schnittstelle in eine "normale" RS-232-Schnittstelle (mit 9pol. D-Sub-Steckverbinder) verwandelt, sowie ein USB-RS232-Adapterkabel, das diese Schnittstelle an USB adaptiert.

Der RS-232-Steckverbinder des AdvaBoard RPi1 führt dabei direkt die RS-232-Schnittstelle des Raspberry Pi auf einen eigenen Steckverbinder heraus. Die Kommunikation über die RS-232-Schnittstelle funktioniert daher exakt genauso wie mit anderen RS-232-Schnittstellen (z.B. per minicom bzw. das /dev/ttyAMA0-Device des Raspberry Pi).

Steckverbinder: Printstecker, 5-polig, RM 2.54mm

RS-232-Einbaustecker	RS-232-Kabel
(Ansicht: Steckseite)

Pin	Signal	Farbe [9]	Beschreibung
1	+5V	rot	Versorgung für externe Peripherie, schaltbar
2	+3.3V	gelb	Versorgung für externe Peripherie max. 100mA zusammen mit I/Os (Pin 1+19) und externen I2C-Geräten
3	GND	schwarz	Masse
4	RX	braun	Receive Data, 0..3.3V, 5V-tolerant
5	TX	orange	Transmit Data, 0..3.3V, 5V-tolerant

[9]	Aderfarbe im RS-232-Kabel des AdvaBoard RPi1-Zubehörsets

8.12   Raspberry Pi

Das AdvaBoard RPi1 wird normalerweise an einen Raspberry Pi angeschlossen und von diesem konfiguriert und gesteuert. Informationen zum Anschluss des AdvaBoard RPi1 an den Raspberry Pi finden Sie im Abschnitt Raspberry Pi-Anschluss.

Steckverbinder: Wannenstecker, 26-polig, RM 2.54mm

Raspberry Pi-Einbaustecker

(Ansicht: Steckseite)

8.13   TFT-Display / Touchscreen

An das AdvaBoard RPi1 kann ein TFT-Display inkl. Touchscreen angeschlossen werden. Weitere Informationen hierzu finden Sie auf der TFT-Display-Seite und in der TFT-Display-Anleitung.

Steckverbinder: Pfostenbuchse, 40-polig, RM 2.54mm

TFT-Display-Einbaubuchse

(Ansicht: Steckseite)

8.14   JTAG/C2-Ausgang

Das AdvaBoard besitzt einen JTAG- und C2-Ausgang, mit dem bestimmte Xilinx CPLDs/FPGAs und bestimmte SiLabs C8051-Mikroprozessoren programmiert werden können. Damit ist z.B. für externe Xilinx-CPLD- oder SiLabs-Mikrocontroller-Platinen kein separates Programmiergerät mehr notwendig.

Zudem ist es möglich, darüber Firmware-Updates in das AdvaBoard einzuspielen, z.B. um später weitere Funktionen nachzurüsten oder das AdvaBoard auf spezielle Anwendungen anzupassen.

8.15   EEPROM

Der Power-Mikrocontroller und der I/O-Mikrocontroller enthalten je eine Art EEPROM, in dem die Konfiguration abgespeichert werden kann. Damit muss das AdvaBoard RPi1 nur einmal konfiguriert werden, und bei jedem Neustart wird die Konfiguration aus dem EEPROM geladen.

Die gespeicherte Konfiguration enthält dabei:

• Power-Mikrocontroller (F912):
  • Kommunikations-Parameter (v.a. I2C-Clock-Stretching-Konfiguration)
  • I/O-, Power- und Echtzeituhr-Zustand nach einem Reset
  • Konfiguration der ereignisgesteuerten Automatisierung
• I/O-Mikrocontroller (F353):
  • Kommunikations-Parameter (v.a. RS-485-Geschwindigkeit und interne I2C-Clock-Stretching-Konfiguration)
  • I/O-Konfiguration der I/Os 0.4..0.7 und 1.0..1.7
  • PWM-Taktfrequenz
  • I/O-Zustand, aktivierte Datenleitungen, RS-485-/RS-232-Konfiguration nach einem Reset
  • Konfiguration der ereignisgesteuerten Automatisierung

Kommandozeilenprogramm:

sudo am_rpi_advaboard_tool -m EEPROM_F912_STORE
sudo am_rpi_advaboard_tool -m EEPROM_F353_STORE

z.B.:

• aktuelle Konfiguration des I/O-Mikrocontrollers speichern:

  $ sudo am_rpi_advaboard_tool -m EEPROM_F912_STORE
  Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)
  
  OK.
  

• aktuelle Konfiguration des Power-Mikrocontroller speichern:

  $ sudo am_rpi_advaboard_tool -m EEPROM_F353_STORE
  Advamation AdvaBoard RPi1 tool, V2014-01-29, (c) Advamation (info@advamation.de)
  
  OK.
  

C-Funktionen (Dokumentation):

am_rpi_advaboard_f912_store(...)
am_rpi_advaboard_f353_store(...)

8.16   Ereignisgesteuerte Automatisierung

Die Mikrocontroller des AdvaBoard RPi1 enthalten eine sogenannte "ereignisgesteuerte Automatisierung" (engl.: event-based automation), wodurch (a) der Zustand nach einem (Power-On-)Reset festgelegt und (b) das AdvaBoard RPi1 auf bestimmte "Ereignisse" selbständig (d.h. ohne den Raspberry Pi) und sehr schnell reagieren kann.

Beispielsweise wäre es dadurch möglich, selbständig die Digital-Eingänge zu überwachen und bei einer Änderung einen I²C-Interrupt auszulösen, einen Analog-Eingang einzulesen sobald ein Schalter gedrückt wird, einen angeschlossenen Motor zu stoppen sobald dieser einen Endschalter erreicht, oder den Raspberry Pi zu einer bestimmten Uhrzeit einzuschalten.

Dadurch können die Echtzeitanforderungen (=schnelle Reaktionszeit auf ein Ereignis) an den Raspberry Pi deutlich reduziert und viele Aufgaben vereinfacht werden.

Der Einschalt-Zustand des AdvaBoards wird ebenfalls über dieses System, bzw. einen dort vorhandenen "Power-On-Reset-Event-Handler", festgelegt.

Die Automatisierung besteht aus zwei Teilen:

• Events: Jeder Mikrocontroller hat eine bestimmte Anzahl an konfigurierbaren "Events". Ein Event kann dabei je nach Konfiguration z.B. ein sich ändernder Digital-Eingang oder ein Alarm der Echtzeituhr sein. Für jedes Event kann zudem eingestellt werden, welchen "Handler" es aufrufen soll.
• Handler: Jeder Mikrocontroller hat eine bestimmte Anzahl an konfigurierbaren "Handlern". Für jeden Handler kann eingestellt werden, welche Aktionen dieser auslösen soll, z.B. das Setzen eines Digital-Ausgangs oder das Einlesen eines Analog-Eingangs.

Der Power-Mikrocontroller und der I/O-Mikrocontroller enthalten jeweils eine eigene derartige ereignisgesteuerte Automatisierung:

# Handler-Flags, manuelles starten eines Handlers:
sudo am_rpi_advaboard_tool -m EVENTPWR_FLAGS
sudo am_rpi_advaboard_tool -m EVENTPWR_CLEAR   flags
sudo am_rpi_advaboard_tool -m EVENTPWR_TRIGGER handler_pwr

# Konfiguration der Handler-Aktionen:
sudo am_rpi_advaboard_tool -m EVENTPWR_POWER_WRITE  handler_pwr PWRON CPLD_3V PERIPHERAL_5V RPi TFT TFT_BL
sudo am_rpi_advaboard_tool -m EVENTPWR_POWER_READ   handler_pwr
sudo am_rpi_advaboard_tool -m EVENTPWR_OUTPUT_WRITE handler_pwr MASK0 OUTPUT0
sudo am_rpi_advaboard_tool -m EVENTPWR_OUTPUT_READ  handler_pwr
sudo am_rpi_advaboard_tool -m EVENTPWR_ANALOGCONTROL_WRITE handler_pwr CONTROL0 CONTROL1 CONTROL2
sudo am_rpi_advaboard_tool -m EVENTPWR_ANALOGCONTROL_READ  handler_pwr

# Konfiguration der Events:
sudo am_rpi_advaboard_tool -m EVENTPWR_I2CINT_WRITE handler_pwr_en
sudo am_rpi_advaboard_tool -m EVENTPWR_I2CINT_READ
sudo am_rpi_advaboard_tool -m RTC_ALARM_SET         i handler_pwr TIME [PERIODIC]
sudo am_rpi_advaboard_tool -m RTC_ALARM_READ        i

am_rpi_advaboard_eventpwr_flags(...)
am_rpi_advaboard_eventpwr_clear(...)
am_rpi_advaboard_eventpwr_trigger(...)

am_rpi_advaboard_eventpwr_output_write(...)
am_rpi_advaboard_eventpwr_output_read(...)
am_rpi_advaboard_eventpwr_analogcontrol_write(...)
am_rpi_advaboard_eventpwr_analogcontrol_read(...)
am_rpi_advaboard_eventpwr_power_write(...)
am_rpi_advaboard_eventpwr_power_read(...)

am_rpi_advaboard_eventpwr_i2cint_write(...)
am_rpi_advaboard_eventpwr_i2cint_read(...)
am_rpi_advaboard_rtc_alarm_write(...)
am_rpi_advaboard_rtc_alarm_set(...)
am_rpi_advaboard_rtc_alarm_read(...)

# Handler-Flags, manuelles starten eines Handlers:
sudo am_rpi_advaboard_tool -m EVENTIO_FLAGS
sudo am_rpi_advaboard_tool -m EVENTIO_CLEAR   flags
sudo am_rpi_advaboard_tool -m EVENTIO_TRIGGER handler_io

# Konfiguration der Handler-Aktionen:
EVENTIO_OUTPUT_WRITE  handler_io MASK0 OUTPUT0 [MASK1 OUTPUT1 [MASK2 OUTPUT2]]
EVENTIO_OUTPUT_READ   handler_io
EVENTIO_CONTROL_WRITE handler_io CONTROL
EVENTIO_CONTROL_READ  handler_io

# Konfiguration der Events:
EVENTIO_EVENT_WRITE  event_io handler_io MASK0 INPUT0 MASK1 INPUT1
EVENTIO_EVENT_READ   event_io

am_rpi_advaboard_eventio_flags(...)
am_rpi_advaboard_eventio_clear(...)
am_rpi_advaboard_eventio_trigger(...)

am_rpi_advaboard_eventio_output_write(...)
am_rpi_advaboard_eventio_output_read(...)
am_rpi_advaboard_eventio_control_write(...)
am_rpi_advaboard_eventio_control_read(...)

am_rpi_advaboard_eventio_event_write(...)
am_rpi_advaboard_eventio_event_read(...)

8.17   Locking / gleichzeitiger Zugriff mehrerer Programme

Häufig ist es notwendig, dass mehrere Programme gleichzeitig auf das AdvaBoard RPi1 zugreifen, z.B. jeweils ein Programm für die Display-Anzeige, das Touchpanel, die Echtzeituhr, ein externes E-SPI-Gerät usw.

Deshalb enthält die AdvaBoard RPi1-Software einen automatischen Locking-Mechanismus, der sicherstellt, dass mehrere Programme "gleichzeitig" auf eine Schnittstelle zuzugreifen können, ohne die Kommunikation der anderen Programme zu kompromittieren, ohne die Schnittstellen-Einstellungen der anderen Programme zu beeinflussen und ohne sich um die Synchronisation mit anderen Programmen kümmern zu müssen.

Voraussetzung hierfür ist jedoch, dass alle Programme, die auf den I²C- oder SPI-Bus des Raspberry Pi zugreifen, dazu ausschließlich die AdvaBoard-Software bzw. -Bibliotheken verwenden.

Wichtig ist, dass dies nur für den gleichzeitigen Zugriff mehrerer Programme gilt. Greifen innerhalb eines Prozesses mehrere Threads auf das AdvaBoard RPi1 zu, so sollte deren Zugriff z.B. mit einer Mutex koordiniert werden.

Es gibt mehrere Locks:

Die Locks sind als Dateilocks (via flock) auf Lockdateien in /var/lock/ implementiert. Damit ist u.a. sichergestellt, dass z.B. die Locks von abgestürzten oder abgebrochenen Programmen automatisch freigegeben werden. Die Lockdateien selbst müssen nie gelöscht werden, da für das Locking nicht ihre Existenz, sondern lediglich ihr flock-Status relevant ist.

Im Normalfall arbeiten die Locks automatisch, ohne dass sich der Programmierer darum kümmern muss. Bei einem Zugriff auf eine Schnittstelle wird automatisch:

1. ggf. gewartet, bis der Lock frei ist
   Wird der Lock innerhalb einer bestimmten Zeit (Timeout) nicht frei, so wird der Zugriff abgebrochen und ein Fehlercode zurückgeliefert.
2. ein entsprechender Lock angelegt
3. die Schnittstelle (um-)konfiguriert
4. die Kommunikation abgewickelt
5. der Lock wieder freigegeben

Es gibt jedoch mehrere Möglichkeiten, das Locking zu beeinflussen:

• Timeout: Für jeden Lock kann eine maximale Zeit eingestellt werden, die auf einen Lock gewartet werden soll. Standardmäßig ist hier 1 Sekunde eingestellt.

• manuelles Locking: Zusätzlich zum automatischen Locking ist es möglich, manuell Locks anzulegen und wieder aufzuheben.

  Dies ist insbesondere dann sinnvoll, wenn mehrere aufeinanderfolgende Kommunikationen mit einem Gerät erfolgen sollen, die nicht durch ein anderes Programm unterbrochen werden dürfen. Zudem kann dies sinnvoll sein, um eine Schnittstelle exklusiv zu verwenden, und den Zugriff anderer Programme auf diese Schnittstelle zu verhindern. Allerdings ist zu beachten, dass dies nur dann wirksam ist, wenn die anderen Programme alle ebenfalls die AdvaBoard-Bibliotheken verwenden; Zugriffe über andere Bibliotheken oder direkt auf die Hardware können dadurch nicht verhindert werden.

C-Funktionen (Dokumentation: AdvaBoard-Bibliothek, TFT-Bibliothek, Raspberry Pi-Bibliothek):

am_rpi_advaboard_spi_lock(...)
am_rpi_advaboard_spi_unlock(...)
am_rpi_advaboard_spi_locking_timeout(...)
am_rpi_spi_lock(...)
am_rpi_spi_unlock(...)
am_rpi_spi_locking_timeout(...)

am_rpi_advaboard_rpii2c_lock(...)
am_rpi_advaboard_rpii2c_unlock(...)
am_rpi_advaboard_rpii2c_locking_timeout(...)
am_rpi_i2c_lock(...)
am_rpi_i2c_unlock(...)
am_rpi_i2c_locking_timeout(...)

am_rpi_advaboard_espi_lock(...)
am_rpi_advaboard_espi_unlock(...)
am_rpi_advaboard_espi_locking_timeout(...)

am_rpi_advaboard_i2c_lock(...)
am_rpi_advaboard_i2c_unlock(...)
am_rpi_advaboard_i2c_locking_timeout(...)

am_rpi_advaboard_f912_lock(...)
am_rpi_advaboard_f912_unlock(...)
am_rpi_advaboard_f912_locking_timeout(...)

am_rpi_advaboard_f353_lock(...)
am_rpi_advaboard_f353_unlock(...)
am_rpi_advaboard_f353_locking_timeout(...)

am_rpi_tft_lock(...)
am_rpi_tft_unlock(...)
am_rpi_tft_locking_timeout(...)

am_rpi_tft_tp_lock(...)
am_rpi_tft_tp_unlock(...)
am_rpi_tft_tp_locking_timeout(...)

Um in Shell-Skripten bzw. mit am_rpi_advaboard_tool manuelle Locks zu verwenden, sollte flock(1) (siehe man 1 flock) , eine Sub-Shell und der Kommandozeilenparameter --nolock genutzt werden. flock legt hierbei den Lock für die Sub-Shell an, --nolock sorgt dafür, dass am_rpi_advaboard_tool keine Locks verwendet (da diese ansonsten mit den Locks der Sub-Shell kollidieren würden), und beim Beenden der Sub-Shell werden die Locks wieder freigegeben.