Example io demo UPDATE 2019

TODO: {{#todo:SEOKWREV (01.03.14-16:47->JG+);(01.03.14-17:35->MD+);(04.07.14-09:45->BS+);(04.09.14-16:15->BS+)|Jgreene|oe 4,oe 5,jg,md,SEOKWREV,ky,bs}}

This demo covers basic GPIO usage for the IPAC single board computer, and 150 and 200 series carrier boards. This demo first cover GPIO manipulation through the Linux terminal and then demonstrates gpio usage in a C program using an io example program.

Hardware Requirements

To use the io demo program you will need the following target hardware.

• An EMAC 150 series carrier board with a compatible SoM
  

OR

• An EMAC 200 series carrier board with a compatible SoM
  

OR

• An IPAC single board computer
  

AND

• additional components to establish to serial and Ethernet connections for your target hardware
  

Software Requirments

These tools should already be installed if you installed the EMAC SDK using the automatic installer.

• EMAC OE 5.X SDK
• EMAC Qt Creator
• GNU make
• CMake

Setup

If you haven't already, please review the EMAC_OE_SDK "getting started" page. EMAC_OE_SDK will need to be installed and serial and network connections will need to be established between the developer machine and the target device.See the Serial Connections or Network Connections page for more information on how to connect to the target EMAC product using a serial port or Ethernet connection.

GPIO manipulation through Linux Terminal

GPIOs can be manipulated directly through the target devices serial terminal. The Libgpiod libary is used for this purpose. Linux terminal commands are defined in the libgpiod github readme (https://github.com/brgl/libgpiod) and are listed here for convenience:

"There are currently six command-line tools available:

gpiodetect - list all gpiochips present on the system, their names, labels and number of GPIO lines

gpioinfo - list all lines of specified gpiochips, their names, consumers, direction, active state and additional flags

gpioget - read values of specified GPIO lines

gpioset - set values of specified GPIO lines, potentially keep the lines exported and wait until timeout, user input or signal

gpiofind - find the gpiochip name and line offset given the line name

gpiomon - wait for events on GPIO lines, specify which events to watch,how many events to process before exiting or if the events should be reported to the console"

GPIO manipulation in C

A more common manipulation of GPIOs is through a C program. The following example will demonstrated GPIO manipulation using the Libgpiod libary.

Program Setup

On the target device:

1. Login, the default username and password is give below:

   username: root
   password: emac_inc
   

2. Change the file to read write by entering oemntrw into the device terminal.

   root@somimx6ul:~# oemntrw

   
   

   
   

   NOTE

   This will only change the root filesystem to read-write for the current boot. When the system is rebooted, the root filesystem will once again be mounted read-only.

3. Obtain the device IP-address by entering ifconfig into the terminal. This is needed for device configuration in Qt Creator below.
   

   root@emac-oe:~# ifconfig
   eth0      Link encap:Ethernet  HWaddr 00:50:C2:E6:60:F4
             inet addr:10.0.2.100  Bcast:10.0.255.255  Mask:255.255.0.0
             inet6 addr: fe80::5054:ff:feb1:f83e/64 Scope:Link
             UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
             RX packets:1825 errors:0 dropped:0 overruns:0 frame:0
             TX packets:553 errors:0 dropped:0 overruns:0 carrier:0
             collisions:0 txqueuelen:1000
             RX bytes:139124 (135.8 KiB)  TX bytes:50603 (49.4 KiB)
             Interrupt:25 Base address:0xc000
   
   lo        Link encap:Local Loopback
             inet addr:127.0.0.1  Mask:255.0.0.0
             inet6 addr: ::1/128 Scope:Host
             UP LOOPBACK RUNNING  MTU:16436  Metric:1
             RX packets:0 errors:0 dropped:0 overruns:0 frame:0
             TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
             collisions:0 txqueuelen:0
             RX bytes:0 (0.0 B)  TX bytes:0 (0.0 B)
   

On development machine:

1. Open Qt Creator

2. Create a new project

   • select + New Project on the 'Welcome' window, the New Project window will appear.
   • Under Projects select Non-Qt Project, Under the middle window select Plain C Application, Click Choose..., The Location window will appear.
   • Name your project LibGPIOd_example, and choose a Create-in location, Click Next > to advance to the Build System window.
   • On the Build System Window choose either the qmake or cmake option (both will be covered in this tutorial), Click Next > to advance to the Kits window.
   • On the Kits window check only ARM Qt5, Click Next > to advance to the Summary window
   • The options on the Summary window will default to <None>, Click Finish'. Your Project will now be generated.

3. Depending on whether you selected the qmake or cmake option the build files (project_name.pro and CMakeLists.txt respectively) will need to be configured.

   • For the qmake option copy and paste the following into your .pro file.

   TEMPLATE = app
   CONFIG += console
   CONFIG -= app_bundle
   CONFIG -= qt
   LIBS +=  -lgpiod
   SOURCES += main.c \
       EMAC_Libgpiod.c
   target.path=/home/developer
   INSTALLS += target
   HEADERS += \
       EMAC_Libgpiod.h
   

   • For the cmake option copy and paste the following into your CMakeLists.txt file.

4. Add the EMAC_Libgpiod.h file

   • With you project selected, click File->New File or Project, the New File or Project window will appear.
   • Under Files and Classes select General, and in the middle column select Empty file, Click Choose..., The Location window will appear
   • Name the file EMAC_Libgpiod.h and choose your project location as the path, Click Next> to advance to the Summary window
   • Click Finish, the file will now open.
   • Copy and paste the provided .h file, EMAC_Libgpiod.h into
   • Save the file, by click File->Save All, the file will now be added to your project under Libgpiod_example->Headers

5. Add the EMAC_Libgpiod.c file

   • repeat same steps as for the .h file, but replace the file name enter EMAC_Libgpiod.c and Copy and paste the provided EMAC_Libgpiod.c file
   • select File->Save All

6. Open main.c under LibGPIOd_example->Sources and copy and paste the provided main.c.

   • Note, the program must be configured to run for your target device. In the main.c file select your target device by un-commenting the #define preprocessor directive corresponding to the device you're using. All other devices should be commented out. For this example we're using a 150ES carrier board so we'll select the CARRIER_BOARD_150.

   //In main.c
   
   #define CARRIER_BOARD_150 
   //#define CARRIER_BOARD_200
   //#define IPAC
   

   Similarly, 1 of 4 example programs can be selected to run, example 4 is selected by default, we'll continue with this option.

   //In main.c
   
   //#define EXAMPLE_1
   //#define EXAMPLE_2
   //#define EXAMPLE_3
   #define EXAMPLE_4
   

   • select File->Save All, All necessary files have now been added to the project

7. Configure build options

   • Go to Tools->Options... to open the options window
   • Select Devices in the left hand column to open the Devices tab
   • From the Devices tab select Devices sub-tab and Click Add... in the right hand column
   • Select Generic Linux Device, then click Start Wizard.
   

   Figure 6: Qt Creator Wizard Selection

   
   

   • Type in a name, the IP address, the user name, and the password for the device. Use the credentials below to sign in.

   Table 4: Default Login Credentials
   Username	Password
   root	emac_inc

   

   Figure 7: Qt Creator Configuration Setup

   
   

   • Click Next.
   • Click Finish.
   • A connection will be established with the target device.
   

   Figure 8: Qt Creator Device Test

   
   

   • Click Close.
   • Click Apply.
   • Now, on the left side of Qt Creator, you will see the project icon, which looks like a monitor. Click this and make sure Arm Qt5 is selected under Kit, Release is selected under Build, and the project is set to be run on the remote device under Run.
   

   Figure 10: Selecting Qt Kit

   
   

   Now, simply press the green play button. The program should run on the target device and yield an output.

   
   

Examples

As previously stated the main.c program must be configured to run for your target device. In the main.c file select your target device by un-commenting the #define preprocessor directive corresponding to the device you're using. All other devices should be commented out.

Similarly, 1 of 4 example programs can be selected to run, un-comment 1 of the "example" #define preprocessor directives and leave the rest commented out. Changes these options will require rebuilding of the program (Simply press the green play button again, this should automatically rebuild and launch the project on the target device.)

All examples use the Libgpiod libary (#include <gpiod.h>), with example 4 using custom built functions provided in EMAC_Libgpiod.h.

EXAMPLE_1 demonstrates basic IO configuration using Libgpiod's contextless functions
EXAMPLE_2 demonstrates basic IO configuration without contextless functions
EXAMPLE_3 LED demo using only Libgpiod
EXAMPLE_4 LED demo using custom built Libgpiod-based helper functions