Difference between revisions of "Zero/dev/libmraa"

Latest revision as of 06:05, 2 December 2021

 Radxa Zero >  Development Guide >  Install Libmraa

Libmraa on Radxa Zero

This guide describes how to use libmraa on Radxa Zero to access GPIO, SPI, and other peripherals.

Requirement

• Radxa Zero
• You need our latest official image

Install essential packages

Prebuilt libmraa is located in our Radxa APT Focal and Buster repositories.

Update your /etc/apt/sources.list.d/apt-radxa-com.list accordingly to enable Radxa APT repository.

For Ubuntu Focal:

root@zero:~# cat /etc/apt/sources.list.d/apt-radxa-com.list 
deb http://apt.radxa.com/focal-stable/ focal main
deb http://apt.radxa.com/focal-testing/ focal main

For Debian Buster:

root@zero:~# cat /etc/apt/sources.list.d/apt-radxa-com.list 
deb http://apt.radxa.com/buster-stable/ buster main
deb http://apt.radxa.com/buster-testing/ buster main

Install libmraa:

rock@zero:~$ sudo apt update
rock@zero:~$ sudo apt install libmraa 

Optionally, install compiler if you want to run some tests:

rock@zero:~$ sudo apt install build-essential

Enable interface

Radxa Zero has a 40-pin color coded expansion header. See Radxa Zero GPIO pintout for more detail on pin definition.

mraa pin definition is configured as follow:

23 GPIO:

   PIN03      GPIOA_14
   PIN05      GPIOA_15
   PIN07      GPIOAO_3
   PIN08      GPIOAO_0
   PIN10      GPIOAO_1
   PIN11      GPIOAO_2
   PIN12      GPIOX_9
   PIN13      GPIOX_11
   PIN16      GPIOX_10
   PIN18      GPIOX_8
   PIN19      GPIOH_4
   PIN21      GPIOH_5
   PIN22      GPIOC_7      //Not supported gpio funtion now
   PIN23      GPIOH_7
   PIN24      GPIOH_6
   PIN27      GPIOAO_3
   PIN28      GPIOAO_2
   PIN32      GPIOAO_4
   PIN35      GPIOAO_8
   PIN36      GPIOH_8
   PIN37      GPIOAO_9
   PIN38      GPIOAO_10
   PIN40      GPIOAO_11

3 I2C:

   PIN23      I2C1_SCL
   PIN24      I2C1_SDA
   PIN13      I2C1_SCL
   PIN16      I2C1_SDA    //these are two i2c-1, only one can be opened when using
   PIN3       I2C3_SDA
   PIN5       I2C3_SCL
   PIN7       I2C4_SDA
   PIN11      I2C4_SCL
   PIN27      I2C4_SDA
   PIN28      I2C4_SCL   ///these are two i2c-4, only one can be opened when using
  

2 SPI: pwm_c

   PIN12      SPI0RX        //must disable i2c1 uart1 pwm_c
   PIN13      SPI0CLK
   PIN16      SPI0CSN
   PIN18      SPI0TX
   PIN19      SPI1TX        //must disable i2c1 uart4
   PIN21      SPI1RX        
   PIN23      SPI1CLK
   PIN24      SPI1CSN

3 UART:

   PIN8       UART0_TX    
   PIN10      UART0_RX
   PIN7       UART1_RX    //must disable i2c4
   PIN11      UART1_TX
   PIN27      UART1_RX
   PIN28      UART1_TX    
   PIN23      UART4_TX    //must disable i2c1 spi1
   PIN24      UART4_RX

2 PWM:

   PIN18      PWM18
   PIN40      PWM40

Since many peripherals are reusing the same physical pin, all but one has to be disabled to allow proper functionality. While in a normal PC user can easily disable or enable peripherals in their UEFI firmware, currently there is no such universal equivalent in ARM world. Instead, Device tree blobs (dtb) and Device tree overlays (dtbo) are used to inform Linux kernel the existence of external devices. Please refer to this guide on available dtbo for Radxa Zero and here on how to specify the correct dtbo. Please read those carefully or you may get an unbootable system.

Run libmraa tests

After set correct dtbo to use, reboot Radxa Zero for change to take effect. You can now try some examples supplied by libmraa. They can be used to test SPI, UART, I2C, GPIO, and so on.

In this example, we will use the sample files located under /usr/local/share/mraa/examples/c.

Let's first copy them to your home directory so we can modify them later:

rock@zero:~$ cp -av /usr/local/share/mraa/examples/c /home/rock/mraa-examples

GPIO test

Use mraa-gpio tool to test GPIO:

root@rockpis:~# mraa-gpio list
01         3V3:  
02          5V: 
03 I2C_EE_M3_S: GPIO I2C  
04          5V: 
05 I2C_EE_M3_S: GPIO I2C  
06         GND: 
07 I2C_AO_M0_S: GPIO I2C  UART 
08 UART_AO_A_T: GPIO UART 
09         GND: 
10 UART_AO_A_R: GPIO UART 
11 I2C_AO_M0_S: GPIO I2C  UART 
12  SPI_A_MISO: GPIO SPI  
13 I2C_EE_M1_S: GPIO I2C  SPI  
14         GND: 
15  SARADC_CH1: 
16 I2C_EE_M1_S: GPIO I2C  SPI  
17         3V3: 
18 SPI_A_MOSI,: GPIO SPI  PWM  
19  SPI_B_MOSI: GPIO SPI  
20         GND: 
21  SPI_B_MISO: GPIO SPI  
22     GPIOC_7: GPIO 
23 I2C_EE_M1_S: GPIO I2C  SPI  UART 
24 UART_EE_C_R: GPIO I2C  SPI  UART 
25         GND: 
26  SARADC_CH2: 
27 I2C_AO_M0_S: GPIO I2C  UART 
28 I2C_AO_M0_S: GPIO I2C  UART 
29          NC: 
30         GND: 
31          NC: 
32    GPIOAO_4: GPIO 
33          NC: 
34         GND: 
35 UART_AO_B_T: GPIO UART 
36     GPIOH_8: GPIO 
37 UART_AO_B_R: GPIO UART 
38   GPIOAO_10: GPIO 
39         GND: 
40     PWMAO_A: GPIO PWM  

root@rockpis:~# mraa-gpio set 40 1           #pin40 pull high
root@rockpis:~# mraa-gpio set 40 0           #pin40 pull low

PWM test

Radxa Zero provides 2 PWM devices: PWM_C and PWMAO_A. It is required to enable them at the same time if you want PWM function.

First, modify /boot/uEnv.txt overlays option as follows:

rock@zero:~$ cat /boot/uEnv.txt 
verbosity=7
console=ttyAML0,115200
overlay_prefix=meson
rootfstype=ext4
fdtfile=amlogic/meson-g12a-radxa-zero.dtb
overlays=meson-g12a-uart-ao-a-on-gpioao-0-gpioao-1 meson-g12a-pwm-c-on-gpiox-8 meson-g12a-pwmao-a-on-gpioao-11
rootuuid=bbe0631f-bbed-4033-8f75-fa5930deceed
initrdsize=0xf1ee3e
kernelversion=5.10.69-5-amlogic-gfeede6ac474e
initrdimg=initrd.img-5.10.69-5-amlogic-gfeede6ac474e
kernelimg=vmlinuz-5.10.69-5-amlogic-gfeede6ac474e

Reboot to apply the change.

Modify the macro PWM in /home/rock/mraa-examples/pwm.c as follows to test PWM_C. To test PWMAO_A, change #define PWM 18 to #define PWM 40.

/* PWM declaration */
#define PWM 18

Save and compile pwm.c:

rock@zero:~/mraa-examples$ gcc -o pwm pwm.c -lmraa
rock@zero:~/mraa-examples$ sudo ./pwm 
PWM value is 0.010015
PWM value is 0.019985
PWM value is 0.030000
PWM value is 0.040014
PWM value is 0.049984
PWM value is 0.059999

I2C test

Radxa Zero provides 3 I2C devices: I2C1, I2C3, and I2C4.

Unlike PWM, if you need the I2C function, you can turn them on separately.

First, modify /boot/uEnv.txt overlays option as follows:

rock@zero:~$ cat /boot/uEnv.txt 
verbosity=7
console=ttyAML0,115200
overlay_prefix=meson
rootfstype=ext4
fdtfile=amlogic/meson-g12a-radxa-zero.dtb
overlays=meson-g12a-uart-ao-a-on-gpioao-0-gpioao-1 meson-g12a-i2c-ee-m1-gpioh-6-gpioh-7
rootuuid=bbe0631f-bbed-4033-8f75-fa5930deceed
initrdsize=0xf1ee3e
kernelversion=5.10.69-5-amlogic-gfeede6ac474e
initrdimg=initrd.img-5.10.69-5-amlogic-gfeede6ac474e
kernelimg=vmlinuz-5.10.69-5-amlogic-gfeede6ac474e

We use MPU6050 example to test I2C. Modify the macro MPU6050 in /home/rock/mraa-examples/i2c_mpu6050.c as follows to test I2C1.

  /* mraa header */
  #include "mraa/i2c.h"
  #define I2C_BUS 0

rock@zero:~/mraa-examples$ gcc -o i2c_mpu6050 i2c_mpu6050.c  -lmraa
rock@zero:~/mraa-examples$ sudo ./i2c_mpu6050
accel: x:0 y:0 z:0
gyro: x:-10 y:1 z:7
  
accel: x:0 y:0 z:0
gyro: x:107 y:-12 z:69
   
accel: x:0 y:0 z:0
gyro: x:6 y:136 z:-50
   
accel: x:0 y:0 z:0
gyro: x:-5 y:48 z:-103
     
accel: x:0 y:0 z:0
gyro: x:3 y:3 z:5

UART test

Radxa Zero provides 3 UART devices: uart0, uart1, and uart4.

Like I2C, you can turn them on separately.

First, disable console and enable uart0 for uart test. Pay attention to ovelays and console options in below file:

rock@zero:~$ cat /boot/uEnv.txt 
verbosity=7
console=ttyAML0,115200
overlay_prefix=meson
rootfstype=ext4
fdtfile=amlogic/meson-g12a-radxa-zero.dtb
overlays=meson-g12a-uart-ao-a-on-gpioao-0-gpioao-1 meson-g12a-uart-ao-b-on-gpioao-2-gpioao-3
console=
rootuuid=bbe0631f-bbed-4033-8f75-fa5930deceed
initrdsize=0xf1ee3e
kernelversion=5.10.69-5-amlogic-gfeede6ac474e
initrdimg=initrd.img-5.10.69-5-amlogic-gfeede6ac474e
kernelimg=vmlinuz-5.10.69-5-amlogic-gfeede6ac474e

Here we set console to NULL.

Reboot to apply the change. While waiting for system to boot up, you can use a jumper wire to short uart0's RX and TX pin, referring to this table if you don't know which pins you need to connect.

In another computer, start 2 SSH sessions, one for sending and one for receiving data via uart0.

Let's first start the receiving end, so it can wait for data input:

rock@zero:~$ sudo mraa-uart dev 0 baud 1500000 recv 1000

In another SSH session, run following command to send data:

rock@zero:~$ sudo mraa-uart dev 0 baud 1500000 send radxa

You should be able to see radxa shown in your first session.

SPI test

Change overlays in /boot/uEnv.txt and reboot:

rock@zero:~$ cat /boot/uEnv.txt 
verbosity=7
console=ttyAML0,115200
overlay_prefix=meson
rootfstype=ext4
fdtfile=amlogic/meson-g12a-radxa-zero.dtb
overlays=meson-g12a-uart-ao-a-on-gpioao-0-gpioao-1 meson-g12a-spi-spidev 
param_spidev_spi_bus=0 
param_spidev_max_freq=10000000
rootuuid=bbe0631f-bbed-4033-8f75-fa5930deceed
initrdsize=0xf1ee3e
kernelversion=5.10.69-5-amlogic-gfeede6ac474e
initrdimg=initrd.img-5.10.69-5-amlogic-gfeede6ac474e
kernelimg=vmlinuz-5.10.69-5-amlogic-gfeede6ac474e

Create file test-spi.c with following content and build:

rock@zero:~/mraa-examples$ cat test-spi.c 
#include <signal.h>
#include <stdlib.h>
#include <unistd.h>

/* mraa header */
#include "mraa/spi.h"

/* SPI declaration */
#define SPI_BUS 0

/* SPI frequency in Hz */
#define SPI_FREQ 10000000
int
main(int argc, char** argv)
{
    mraa_result_t status = MRAA_SUCCESS;
    mraa_spi_context spi;
    int i, j;

    /* initialize mraa for the platform (not needed most of the times) */
    mraa_init();

    //! [Interesting]
    /* initialize SPI bus */
    spi = mraa_spi_init(SPI_BUS);
    if (spi == NULL) {
        fprintf(stderr, "Failed to initialize SPI\n");
        mraa_deinit();
        return EXIT_FAILURE;
    }

    /* set SPI frequency */
    status = mraa_spi_frequency(spi, SPI_FREQ);
    if (status != MRAA_SUCCESS)
        goto err_exit;

    /* set big endian mode */
    status = mraa_spi_lsbmode(spi, 0);
    if (status != MRAA_SUCCESS) {
        goto err_exit;
    }
   
    j = 10;
    while(j) {
  	j--;
        printf("0x%x\n",mraa_spi_write(spi, 0xaa));
    }
err_exit:
    mraa_result_print(status);

    /* stop spi */
    mraa_spi_stop(spi);

    /* deinitialize mraa for the platform (not needed most of the times) */
    mraa_deinit();

     return EXIT_FAILURE;
}
rock@zero:~/mraa-examples$ gcc -o test-spi test-spi.c -lmraa

Then short PIN12 and PIN18 and run test-spi:

rock@zero:~/mraa-examples$ sudo ./test-spi 
0xaa
0xaa
0xaa
0xaa
0xaa
0xaa
0xaa
0xaa
0xaa
0xaa
MRAA: SUCCESS

Development

You can find libmraa's documentation here.