PineDio Stack BL604 runs Apache NuttX RTOS

📝 12 Apr 2022

Pine64 PineDio Stack BL604 RISC-V Board

PineDio Stack BL604 is Pine64’s newest microcontroller board, based on Bouffalo Lab’s BL604 RISC-V + WiFi + Bluetooth LE SoC.

(Available any day now!)

PineDio Stack is packed chock-full of features…

• ST7789 Colour LCD Display

  (240 x 240 pixels)

• CST816S Touch Panel

  (Connected on I2C)

• Semtech SX1262 LoRa Transceiver

  (Works with LoRaWAN wireless networks)

• AT6558 GPS / GNSS Receiver

• SGM40561 Power Management Unit

• Heart Rate Sensor, Accelerometer, Compass, Vibrator

• SPI Flash, JTAG Debugging Port, Push Button

• 2.4 GHz WiFi, Bluetooth LE

  (Thanks to BL604)

Which makes it an awesome gadget for IoT Education!

(It looks like a “Chonky PineTime”… It has the same display and touch panel as PineTime)

Today we shall build, flash and run the open-source, community-supported Apache NuttX RTOS (Real-Time Operating System) on PineDio Stack…

And get started on creating our own IoT Apps!

Pine64 PineDio Stack BL604 RISC-V Board

§1 What is NuttX?

Apache NuttX is a popular Real-Time Operating System (RTOS) for microcontrollers (8-bit to 64-bit). It runs on all kinds of hardware: Arm, ESP32, RISC-V, … Even flying drones!

NuttX feels like a lighter version of Linux because it uses familiar functions to access the microcontroller hardware: open(), read(), write(), ioctl(), …

(NuttX is POSIX Compliant)

We’ve done many fun experiments with NuttX on BL602 and BL604: ST7789 Display, BME280 Sensor, IKEA Air Quality Sensor, Internal Temperature Sensor, LoRa, LoRaWAN, Rust, BASIC, CBOR, … And now PineDio Stack.

The source code for NuttX on PineDio Stack is here…

• lupyuen/nuttx (pinedio branch)

• lupyuen/nuttx-apps (pinedio branch)

  (Yep I’m a NuttX Contributor)

Let’s go hands-on with NuttX!

§2 Build NuttX

NuttX builds fine on Linux (x64), macOS and Windows Subsystem for Linux (WSL).

Here are the steps to build NuttX for PineDio Stack…

1. Install the build prerequisites…

   “Install Prerequisites”

2. Enter these commands to download, configure and build NuttX…

   ##  Download NuttX for PineDio Stack
   mkdir nuttx
   cd nuttx
   git clone --recursive --branch pinedio https://github.com/lupyuen/nuttx nuttx
   git clone --recursive --branch pinedio https://github.com/lupyuen/nuttx-apps apps
   
   ##  Configure NuttX for PineDio Stack
   cd nuttx
   ./tools/configure.sh bl602evb:pinedio
   
   ##  Build NuttX for PineDio Stack
   make

3. We should see…

   LD: nuttx
   CP: nuttx.hex
   CP: nuttx.bin

   We have successfully built the NuttX Firmware for PineDio Stack!

   (See the WSL Build Log)

   (See the macOS Build Log)

4. For WSL: Copy the NuttX Firmware to the c:\blflash directory in the Windows File System…

   ##  /mnt/c/blflash refers to c:\blflash in Windows
   mkdir /mnt/c/blflash
   cp nuttx.bin /mnt/c/blflash

   We’ll flash PineDio Stack with Windows Command Prompt (CMD) because we need the COM port.

What’s “bl602evb:pinedio”?

That’s the NuttX Build Configuration for PineDio Stack. It selects the Build Options, NuttX Drivers and NuttX Apps that will run on PineDio Stack.

(See the bundled features)

§3 Prepare PineDio Stack

Let’s get ready to flash the NuttX Firmware to PineDio Stack!

• Connect PineDio Stack to our computer’s USB Port.

  The Self Test screen appears. (Pic above)

  Tap each button to verify that PineDio Stack is OK.

  (We should see this)

• Disconnect PineDio Stack from the USB Port.

  Carefully open the Back Cover of PineDio Stack. (Pic above)

  (Don’t remove the display!)

  We’ll see the PineDio Stack Baseboard…

• Carefully remove the PineDio Stack Baseboard.

  We’ll see the Main Board…

What’s on the Main Board?

• GPIO 8 Jumper (top right): Set PineDio Stack to Flashing Mode or Normal Mode

• Improvised Reset Button (lower left): We connect a Jumper Cable (to the I2C Port) to restart PineDio Stack during flashing and testing

• LoRa Antenna (bottom): Connect an antenna here if we’re testing LoRa

• WiFi / Bluetooth LE Antenna (right): Connect an antenna here if we’re testing WiFi or Bluetooth LE

• JTAG Port (top left): For debugging (but not flashing)

• GPIO Port (lower right): Connects the baseboard

• Push Button (just below the jumper): Works like a watch button

Check out the PineDio Stack Schematics…

• PineDio Stack Schematic (2021-09-15)

• PineDio Stack Baseboard Schematic (2021-09-27)

We’re ready to flash PineDio Stack!

(Source)

§4 Flash PineDio Stack

Let’s flash the NuttX Firmware to PineDio Stack. Follow these steps to install blflash…

• “Install rustup”

• “Download blflash”

Set PineDio Stack to Flashing Mode and restart the board…

1. Set the GPIO 8 Jumper to High (Like this)

2. Disconnect the USB cable and reconnect

   Or use the Improvised Reset Button (Here’s how)

Enter these commands to flash nuttx.bin to PineDio Stack…

(For WSL: Do this in Windows Command Prompt CMD instead of WSL. blflash needs to access the COM port)

## For Linux: Change "/dev/ttyUSB0" to the PineDio Stack Serial Port
blflash flash nuttx.bin \
  --port /dev/ttyUSB0 

## For macOS: Change "/dev/tty.usbserial-1410" to the PineDio Stack Serial Port
blflash flash nuttx.bin \
  --port /dev/tty.usbserial-1410 \
  --initial-baud-rate 230400 \
  --baud-rate 230400

## For Windows: Change "COM5" to the PineDio Serial Port
blflash flash c:\blflash\nuttx.bin --port COM5

We should see…

Sending eflash_loader...
Erase flash addr: 10000 size: 565200
Program flash...
Program done 27.434715128s 20.12KiB/s
Success

(See the Flash Log)

NuttX has been flashed to PineDio Stack!

Will PineDio Stack get bricked if we flash bad firmware?

After using BL602 and BL604 for 1.5 years, I’ve never bricked a single BL602 or BL604 board.

So go ahead and create your own PineDio Stack firmware, it’s all OK!

(Flashing WiFi apps? See this)

§5 Boot PineDio Stack

Like Linux, NuttX provides a Command-Line Interface for controlling our gadget. This is how we access the NuttX Shell…

Set PineDio Stack to Normal Mode (Non-Flashing) and restart the board…

1. Set the GPIO 8 Jumper to Low (Like this)

2. Disconnect the USB cable and reconnect

   Or use the Improvised Reset Button (Here’s how)

After restarting, connect a Serial Terminal to PineDio Stack at 2 Mbps…

For Linux: Use screen

screen /dev/ttyUSB0 2000000

For macOS: Use CoolTerm (See this)

For Windows: Use putty (See this)

Alternatively: Use the Web Serial Terminal (See this)

Press Enter to reveal the NuttX Shell…

NuttShell (NSH) NuttX-10.2.0-RC0
nsh>

Congratulations NuttX is now running on PineDio Stack!

§6 Run NuttX

NuttX boots with a Pink Screen. (Pic above)

In the NuttX Shell, enter this command…

ls /dev

We see a list of Device Drivers that were loaded by NuttX. (Pic below)

Now that NuttX is up, let’s run some NuttX Apps!

(Source)

(UPDATE: We have renumbered the GPIOs)

§7 NuttX Apps

In the NuttX Shell, enter this command…

help

(“?” works too)

We see a list of NuttX Apps that have been installed…

Builtin Apps:
  bas             lorawan_test  spi_test2
  bl602_adc_test  lvgltest      sx1262_test
  getprime        nsh           timer
  gpio            sensortest    tinycbor_test
  hello           spi
  i2c             spi_test
  ikea_air_quality_sensor

Enter this to run the LVGL Test App…

lvgltest

Follow the prompts to tap the screen and calibrate the Touch Panel.

After calibrating, this appears on the screen: “Hello PineDio Stack!” with a funky blue-green box…

Can we render our own text and graphics?

Sure can! Below is the code that renders the screen, by calling the LVGL Graphics Library…

//  Create the LVGL Widgets that will be rendered on the display
static void create_widgets(void) {
  //  Get the Active Screen
  lv_obj_t *screen = lv_scr_act();

  //  Create a Label Widget
  lv_obj_t *label = lv_label_create(screen, NULL);

  //  Wrap long lines in the label text
  lv_label_set_long_mode(label, LV_LABEL_LONG_BREAK);

  //  Interpret color codes in the label text
  lv_label_set_recolor(label, true);

  //  Center align the label text
  lv_label_set_align(label, LV_LABEL_ALIGN_CENTER);

  //  Set the label text and colors
  lv_label_set_text(
    label, 
    "#ff0000 HELLO# "    //  Red Text
    "#00ff00 PINEDIO# "  //  Green Text
    "#0000ff STACK!# "   //  Blue Text
  );

  //  Set the label width
  lv_obj_set_width(label, 200);

  //  Align the label to the center of the screen, shift 30 pixels up
  lv_obj_align(label, NULL, LV_ALIGN_CENTER, 0, -30);

  //  Omitted: Render a rounded rectangle with LVGL Canvas

(Source)

To render our own text and graphics, edit this source file and change the code above…

apps/examples/lvgltest/lvgltest.c

Then rebuild (“make”) and reflash (“blflash”) NuttX to PineDio Stack.

(More about LVGL)

So touchscreen apps are supported on PineDio Stack?

Yep! See this for the details…

• “PineDio Stack Touch Panel”

(Source)

§8 More Apps

What other NuttX Apps can we try?

• hello: Prints “Hello World”

  (Source code)

• bl602_adc_test: Shows the Internal Temperature of BL604

  (See this)

• bas: BASIC Interpreter (Ctrl-D to quit)

  (See this)

(Here’s a demo of the apps)

What about LoRa on PineDio Stack?

We have NuttX Apps for testing LoRa and LoRaWAN wireless networking.

See the Appendix for details…

• “SX1262 LoRa Transceiver”

If we wish to create our own NuttX Apps?

Refer to the docs for the steps to create our own NuttX Apps, Libraries and Drivers…

• “How To Create NuttX Apps”

• “How To Create NuttX Libraries”

• “How To Create NuttX Device Drivers”

Here are some Troubleshooting Tips…

• “NuttX Logging”

• “NuttX Crash Analysis”

Also check out the NuttX Articles on all kinds of topics…

• “NuttX on BL602 / BL604”

Shared SPI Bus on PineDio Stack

§9 Upcoming Features

So PineDio Stack runs all hunky dory on NuttX?

Not completely. PineDio Stack’s Shared SPI Bus works great on NuttX after we modded the SPI Driver…

• “Shared SPI Bus”

The ST7789 Display runs well with NuttX’s ST7789 Driver and LVGL Library right out of the box, with one tweak…

• “ST7789 SPI Mode”

And the SX1262 LoRa Transceiver works fine with Semtech’s Reference Drivers for LoRa and LoRaWAN…

• “SX1262 LoRa Transceiver”

But there’s plenty more porting work to be done!

• GPIO Expander

• Push Button

• Accelerometer

• Power Management

• GPS

• SPI Flash

• SPI Direct Memory Access

• Automated Testing

If you’re keen to help, please lemme know! 🙏

§10 What’s Next

I hope this article has provided everything you need to get started on creating your own IoT App.

Lemme know what you’re building with PineDio Stack!

Many Thanks to my GitHub Sponsors for supporting my work! This article wouldn’t have been possible without your support.

• Sponsor me a coffee

• Discuss this article on Reddit

• Read “The RISC-V BL602 / BL604 Book”

• Check out my articles

• RSS Feed

Got a question, comment or suggestion? Create an Issue or submit a Pull Request here…

lupyuen.github.io/src/pinedio2.md

§11 Notes

1. This article is the expanded version of this Twitter Thread

2. Got a question for Bouffalo Lab? Check out their Developer Forum…

   “Bouffalo Lab Developer Forum”

3. Also check out the Nutcracker Channel on Matrix, Telegram, Discord or IRC…

   “Pine64 Chat Platforms”

4. Besides NuttX, there are two other ways to code firmware for PineDio Stack…

   BL IoT SDL: Supports WiFi and is based on FreeRTOS

   BL MCU SDK: Doesn’t support WiFi, also based on FreeRTOS)

5. The PineDio Stack Self-Test Firmware was created by JF with BL MCU SDK…

   JF002/pinedio-stack-selftest

6. LVGL Canvas consumes a lot of RAM! Disable it if we don’t really need it, we’ll save 7 KB of RAM…

   Configure NuttX with “make menuconfig”

   Select “Application Configuration → Graphics Support → Light and Versatile Graphic Library (LVGL) → Object Type Usage Settings”

   Uncheck “Canvas Usage”

   Save and exit menuconfig, then rebuild NuttX (make)

7. The Baseboard Schematic includes a Secure Chip ATECC608A. We talk about it here…

   “Cryptographic Co-Processor”

8. What’s it like to test the First (Buggy) Prototype of PineDio Stack? Find out here…

   “PineDio Stack BL604 RISC-V Board: Testing The Prototype”

§12 Appendix: GPIO Assignment

Acording to the PineDio Stack Schematics…

• PineDio Stack Schematic (2021-09-15)

• PineDio Stack Baseboard Schematic (2021-09-27)

These are the BL604 GPIOs used by PineDio Stack…

• SPI Bus “/dev/spi0” is shared by ST7789 Display, SX1262 LoRa Transceiver and SPI Flash

• Internal I2C Bus “/dev/i2c0” is shared by Accelerometer, Touch Panel, Heart Rate Sensor and Compass

• UART Port “/dev/console” is shared by Serial Console and GPS

  (This will be a problem, in spite of their different baud rates)

• GPIO Ports “/dev/gpio0” to “/dev/gpio22” are mapped to GPIO Pins 0 to 22

  (Except the pins reserved for the UART, I2C and SPI Ports)

The NuttX Pin Definitions for PineDio Stack are at…

boards/risc-v/bl602/bl602evb/include/board.h

§13 Appendix: Bundled Features

Earlier we ran this command to configure the NuttX Build for PineDio Stack BL604…

./tools/configure.sh bl602evb:pinedio

The above command bundles the following NuttX Drivers, Libraries and Apps into NuttX for PineDio Stack…

• BL602 ADC Library

  (Used by LoRaWAN Test App)

• I2C Driver “/dev/i2c0”

  (Used by I2C Sensors)

• LCD Driver “/dev/lcd0”

  (Used by LVGL Test App)

• LoRa SX1262 Library

  (Used by LoRaWAN Library)

• LoRaWAN Library

  (Used by LoRaWAN Test App)

• LVGL Graphics Library

  (Used by LVGL Test App)

• NimBLE Porting Layer

  (Used by LoRa SX1262 Library)

• Rust Stub Library

  (Used by Rust Apps)

• Sensor Test App

  (For testing I2C Sensors)

• SPI Driver “/dev/spi0”

  (Used by SPI Test Driver)

  (And ST7789 Display Driver)

• SPI Test Driver “/dev/spitest0”

  (Used by LoRa SX1262 Library)

• ST7789 Display Driver

  (Used by the LCD Driver)

• TinyCBOR Library

  (Used by TinyCBOR Test App)

The NuttX Configuration File for PineDio Stack is at…

boards/risc-v/bl602/bl602evb/configs/pinedio/defconfig

§14 Appendix: Upcoming Features

This section discusses the upcoming features that we’ll implement with NuttX on PineDio Stack BL604.

If you’re keen to help, please lemme know! 🙏

(Schematic)

§14.1 GPIO Expander

UPDATE: We have implemented the GPIO Expander, so we’re no longer stuck with 3 GPIOs

BL604 has 23 GPIOs. Can we use all of them in NuttX Apps?

Some of the GPIOs will be used for SPI, I2C and UART. But we still have a lot of remaining GPIOs to manage!

NuttX allows apps to access to a total of 3 GPIOs on BL604…

• /dev/gpio0: GPIO Input

  (Configured as GPIO 10)

• /dev/gpio1: GPIO Output

  (Configured as GPIO 15)

• /dev/gpio2: GPIO Interrupt

  (Configured as GPIO 19)

(All 3 GPIOs are already used by the SX1262 Library. See this)

Adding the remaining GPIOs to the BL604 GPIO Driver at compile-time will be cumbersome. (See this)

We need a flexible way to manage many GPIOs at runtime, as we build new apps and drivers for PineDio Stack.

Is there a way to aggregate the GPIOs without defining them at compile-time?

NuttX supports GPIO Expanders that will aggregate multiple GPIOs…

• Sample I/O Expander

• Skeleton I/O Expander

• Lower Half of I/O Expander

• Usage of I/O Expander

We shall implement a GPIO Expander for BL604 that will handle multiple GPIOs by calling bl602_configgpio, bl602_gpioread and bl602_gpiowrite.

The GPIO Expander will expose GPIOs 0 to 22 as “/dev/gpio0” to “/dev/gpio22”.

Won’t this break the existing GPIOs that are in use?

We’ll skip “/dev/gpio0” to “/dev/gpio2” because they are already used by the SX1262 Driver. (See this)

(On PineDio Stack: GPIO 0 is MISO, GPIO 1 is SDA, GPIO 2 is SCL. So we shouldn’t touch GPIOs 0, 1 and 2 anyway. See this)

Wow this sounds messy?

But it might be the most productive way (for now) to handle so many GPIOs while multiple devs are building apps and drivers for PineDio Stack.

Perhaps the GPIO Expander can enforce checks at runtime to be sure that NuttX Apps don’t tamper with the GPIOs used by SPI, I2C and UART.

(And eventually the SX1262 Library will simply access “/dev/gpio10”, “/dev/gpio15” and “/dev/gpio19”)

More details on the GPIO Expander…

• BL602 / BL604 GPIO Expander

The GPIO Expander shall also manage GPIO Interrupts for the Touch Panel, SX1262 Transceiver, Push Button, Compass, Accelerometer, Heart Rate Sensor, …

• “GPIO Interrupt”

There’s a discussion about GPIOs on BL604…

• “GPIO issues on BL602”

NuttX Apps vs NuttX Drivers… Do they handle GPIOs differently?

• NuttX Drivers run in Kernel Mode and can access the GPIO Hardware directly by calling bl602_configgpio, bl602_gpioread and bl602_gpiowrite.

  (So no problems handling many GPIOs)

• NuttX Apps run in User Mode and can only access GPIOs through “/dev/gpioN”

  (Which becomes a problem when we have many GPIOs)

NuttX Apps are easier to code than NuttX Drivers.

(That’s our experience with LoRa)

Thus we expect most PineDio Stack devs to create NuttX Apps first before moving the code into NuttX Drivers.

That’s why we need to handle GPIOs the messy (but productive) way for now.

(More about NuttX GPIO)

§14.2 Push Button

Robert Lipe has an excellent article on PineDio Stack’s Push Button…

• “Buttons on BL602 NuttX”

To support the Push Button (GPIO 12) on PineDio Stack, we shall implement these Board Button Functions for PineDio Stack…

• board_buttons

• board_button_irq

• board_button_initialize

(Here’s the implementation for ESP32)

They will be called by the Button Lower Half Driver in NuttX…

• Button Lower Half Driver

Which is wrapped inside the Button Upper Half Driver and exposed to apps as “/dev/buttons”…

• Button Upper Half Driver

(Here’s how we access “/dev/buttons” in NuttX Apps)

Note that the Push Button shares GPIO 12 with the Vibrator.

(Which is missing from the current PineDio Stack)

(Schematic)

§14.3 Touch Panel

JF has created a CST816S I2C Touch Panel Driver for PineDio Stack… (Thanks JF!)

• pinedio-stack-selftest/drivers/cst816s.c

We have ported this driver to NuttX and exposed it to apps as a NuttX Touchscreen Device “/dev/input0”…

• lupyuen/cst816s-nuttx

(Here’s how we access “/dev/input0” in our LVGL Test App)

More about the NuttX Touch Panel Driver for PineDio Stack…

• “NuttX Touch Panel Driver for PineDio Stack BL604”

(PineDio Stack uses the same Touch Panel as PineTime)

(More about NuttX Touchscreen Drivers)

(Schematic)

§14.4 Accelerometer

To create the I2C Accelerometer Sensor Driver “/dev/accel0” for PineDio Stack, we could port JF’s simple driver…

• pinedio-stack-selftest/accelerometer.c

Or the Reference Driver for MC3416…

• MC3416 Driver Source Code

The NuttX Driver for WTGAHRS2 Accelerometer might be a good guide for porting the driver.

We have an article that explains the innards of NuttX Sensor Drivers…

• “Apache NuttX Driver for BME280 Sensor: Ported from Zephyr OS”

NuttX’s I2C Tool might be helpful for troubleshooting I2C Drivers.

(Schematic)

§14.5 Power Management

Check out JF’s driver for SGM40561 Power Management Unit…

• pinedio-stack-selftest/battery.c

(This is the same Power Management Unit used in PineTime)

To port this to NuttX, we’ll call the BL604 ADC Library…

• “ADC and Internal Temperature Sensor Library”

(Because BL604 ADC is not supported yet on NuttX)

Refer to the Power Management Drivers for NuttX…

• nuttx/drivers/power

(Schematic)

§14.6 GPS

NuttX has a GPS Demo App…

• apps/examples/gps

And a GPS Parser Library…

• apps/gpsutils

These might be helpful for creating the GPS Driver (UART) for PineDio Stack.

(Schematic)

§14.7 SPI Flash

The PineDio Stack Schematics refer to 2 kinds of SPI Flash… (Why?)

• MX25R1635FZUIL0 (Main Board)

• W25Q128FV / W25Q256FV (Baseboard)

Both kinds of SPI Flash seem to be supported by NuttX…

• NuttX MX25RXX Driver

• NuttX W25 Driver

We need to test the drivers.

NuttX’s SPI Tool might be helpful for troubleshooting SPI Drivers.

§14.8 SPI Direct Memory Access

ST7789 Display receives plenty of data on the SPI Bus (for screen updates). Will there be contention with other SPI Devices? (Like SX1262 Transceiver)

Most definitely. That’s why we need to implement SPI Direct Memory Access (DMA) so that PineDio Stack can do other tasks while painting the ST7789 Display.

(Right now the SPI Driver polls the SPI Port when transferring SPI data)

We’ll port to NuttX this implementation of SPI DMA from BL MCU SDK…

• bl602_dma.c

More about SPI DMA on BL602 / BL604…

• “SPI with Direct Memory Access”

• “Create DMA Linked List”

• “Execute DMA Linked List”

UPDATE: SPI DMA is now supported on BL602 / BL604 NuttX…

• “SPI DMA on BL602 NuttX”

PineCone BL602 RISC-V Board (bottom) connected to Single-Board Computer (top) for Auto Flash and Test

§14.9 Automated Testing

UPDATE: Automated Testing for PineDio Stack is explained in this article…

• “(Mostly) Automated Testing of Apache NuttX RTOS on PineDio Stack BL604 RISC-V Board”

When we have multiple devs creating NuttX Apps and Drivers for PineDio Stack, it might be good to run some Automated Testing (to be sure that nothing’s broken).

Today we run a Daily Automated Test on the NuttX Mainline Branch for PineCone BL602…

• “Auto Flash and Test NuttX on RISC-V BL602”

  (See the Automated Test Logs)

Now we need to connect an SBC to PineDio Stack and auto-run these tests…

• SPI Test App (spi_test2): Verify that the SPI Driver can talk to SX1262

• LoRaWAN Test App (lorawan_test): Verify that SX1262 can join a LoRaWAN Network (ChirpStack) and transmit Data Packets

• LVGL Test App (lvgltest): Verify that ST7789 can render an LVGL Screen (over SPI) and read the CST816S Touch Panel (over I2C)

• GPIO Command (gpio): Verify that the BL604 GPIO Expander correctly triggers an interrupt when the Push Button is pressed…

  nsh> gpio -t 8 -w 1 /dev/gpio12
  Driver: /dev/gpio12
    Interrupt pin: Value=1
    Verify:        Value=1

  (Source)

Right now we run these tests manually on PineDio Stack when we update the pinedio branch.

We record the Manual Test Logs in the Pull Requests…

• Pull Requests and Manual Test Logs for PineDio Stack

So we’ll run Automated Tests on PineCone BL602 AND PineDio Stack BL604?

Yep we shall test and maintain two Stable Branches of NuttX for public consumption…

• master branch for PineCone BL602

• pinedio branch for PineDio Stack BL604

(Same for NuttX Apps)

Are the branches any different?

The code should be identical, though…

• PineCone BL602 won’t use the Shared SPI Bus that we have created for PineDio Stack BL604

• PineCone BL602 won’t use the GPIO Expander either

We control the options through the NuttX Build Configuration…

## Configure build for PineDio Stack BL604
./tools/configure.sh bl602evb:pinedio

## Configure build for PineCone BL602
./tools/configure.sh bl602evb:pinecone

(See the PineDio Stack config)

(See the PineCone config)

This check for PineDio Stack should probably be improved: board.h

/* Identify as PineDio Stack if both ST7789 and CST816S are present */
#if defined(CONFIG_LCD_ST7789) && defined(CONFIG_INPUT_CST816S)
#define PINEDIO_STACK_BL604
#endif /* CONFIG_LCD_ST7789 && CONFIG_INPUT_CST816S */

(PINEDIO_STACK_BL604 enables the SPI Device Table in the SPI Driver)

(Source)

What about upstream updates from NuttX Mainline Branch?

• Upstream updates from NuttX Mainline will first be merged and auto-tested in the downstream branch

  (Every 2 weeks, depends on my writing mood)

• Then merged and auto-tested in the master (release) branch

  (For PineCone BL602)

• Which gets merged and manually tested in the pinedio branch

  (For PineDio Stack BL604)

• Updates in the pinedio branch are merged back to the master and the downstream branches and auto-tested on PineCone BL602

• Thus ultimately the pinedio, master and downstream branches will all have the exact same code, tested OK on PineCone BL602 and PineDio Stack BL604

  (And lagging behind NuttX Mainline by 2 weeks)

This is an extension of our original grand plan…

• “Merge Updates From NuttX”

But how will we auto-test the Touch Panel on PineDio Stack?

With a Robot Finger?

Or let our SBC actuate a Motor that’s wrapped in an Anti-Static Bag?

• Watch the video on YouTube

I’m open to ideas, please lemme know! 🙏

PineDio Stack BL604 RISC-V Board (left) talking LoRaWAN to RAKwireless WisGate LoRaWAN Gateway (right)

§15 Appendix: SX1262 LoRa Transceiver

PineDio Stack BL604 includes a Semtech SX1262 LoRa Transceiver for wireless networking.

This section explains how we may test LoRa and LoRaWAN Wireless Networking on PineDio Stack.

CAUTION: Always connect the LoRa Antenna before testing LoRa or LoRaWAN… Or the LoRa Transceiver may get damaged! (Pic above)

Why LoRa?

LoRa is a Low-Power, Long-Range, Low-Bandwidth wireless network.

LoRa is perfect for IoT Sensor Devices that run on Battery Power. (Or Solar Power)

Will LoRa support all kinds of messages?

Not quite. LoRa only supports Short Messages of up to 242 Bytes.

And because LoRa is a Low Power (best effort) network, messages may get dropped. Which is probably OK for sensor devices that send data periodically.

(But not for texting your friends)

Is LoRa secure?

LoRa messages are delivered securely when we join a LoRaWAN Network.

Today we shall test both LoRa and LoRaWAN on PineDio Stack…

• Transmit and receive raw LoRa Messages

• Join a LoRaWAN Network and transmit a LoRaWAN Message to a LoRaWAN Gateway (like ChirpStack or The Things Network)

(More about LoRa and LoRaWAN)

§15.1 Test LoRa

The LoRa Library for Semtech SX1262 is explained in this article…

• “LoRa SX1262 on Apache NuttX OS”

To test LoRa on PineDio Stack, edit sx1262_test_main.c at…

apps/examples/sx1262_test/sx1262_test_main.c

And update the LoRa Parameters…

/// TODO: We are using LoRa Frequency 923 MHz 
/// for Singapore. Change this for your region.
#define USE_BAND_923
...

/// LoRa Parameters
#define LORAPING_TX_OUTPUT_POWER            14        /* dBm */

#define LORAPING_BANDWIDTH                  0         /* [0: 125 kHz, */
                                                      /*  1: 250 kHz, */
                                                      /*  2: 500 kHz, */
                                                      /*  3: Reserved] */
#define LORAPING_SPREADING_FACTOR           7         /* [SF7..SF12] */
#define LORAPING_CODINGRATE                 1         /* [1: 4/5, */
                                                      /*  2: 4/6, */
                                                      /*  3: 4/7, */
                                                      /*  4: 4/8] */
#define LORAPING_PREAMBLE_LENGTH            8         /* Same for Tx and Rx */
#define LORAPING_SYMBOL_TIMEOUT             5         /* Symbols */
#define LORAPING_FIX_LENGTH_PAYLOAD_ON      false
#define LORAPING_IQ_INVERSION_ON            false

#define LORAPING_TX_TIMEOUT_MS              3000    /* ms */
#define LORAPING_RX_TIMEOUT_MS              10000    /* ms */
#define LORAPING_BUFFER_SIZE                64      /* LoRa message size */

(Source)

The parameters are explained here…

• “LoRa Parameters”

Then uncomment SEND_MESSAGE or RECEIVE_MESSAGE to send or receive a LoRa Message…

int main(int argc, FAR char *argv[]) {
...
//  Uncomment to send a LoRa message
#define SEND_MESSAGE
...
//  Uncomment to receive a LoRa message
#define RECEIVE_MESSAGE

(Source)

Rebuild (“make”) and reflash (“blflash”) NuttX to PineDio Stack.

In the NuttX Shell, enter this to run the LoRa Test App…

sx1262_test

If we’re sending a LoRa Message on PineDio Stack, we’ll see the message received by the LoRa Receiver Device…

• “Run the Firmware”

To troubleshoot LoRa, we could use a Spectrum Analyser (Software-Defined Radio)…

• “Spectrum Analysis with SDR”

§15.2 Test LoRaWAN

The LoRaWAN Library is explained in this article…

• “LoRaWAN on Apache NuttX OS”

To test LoRaWAN on PineDio Stack, we edit se-identity.h at…

nuttx/libs/liblorawan/src/peripherals/soft-se/se-identity.h

And update the LoRaWAN Parameters…

//  End-device IEEE EUI (big endian)
#define LORAWAN_DEVICE_EUI { 0x4b, 0xc1, 0x5e, 0xe7, 0x37, 0x7b, 0xb1, 0x5b }

//  App/Join server IEEE EUI (big endian)
#define LORAWAN_JOIN_EUI { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 }
...
#define SOFT_SE_KEY_LIST \
  { \
    { \
      /*! \
       * Application root key \
       * WARNING: FOR 1.0.x DEVICES IT IS THE \ref LORAWAN_GEN_APP_KEY \
       */ \
      .KeyID    = APP_KEY, \
      .KeyValue = { 0xaa, 0xff, 0xad, 0x5c, 0x7e, 0x87, 0xf6, 0x4d, 0xe3, 0xf0, 0x87, 0x32, 0xfc, 0x1d, 0xd2, 0x5d }, \
    }, \
    { \
      /*! \
       * Network root key \
       * WARNING: FOR 1.0.x DEVICES IT IS THE \ref LORAWAN_APP_KEY \
       */ \
      .KeyID    = NWK_KEY, \
      .KeyValue = { 0xaa, 0xff, 0xad, 0x5c, 0x7e, 0x87, 0xf6, 0x4d, 0xe3, 0xf0, 0x87, 0x32, 0xfc, 0x1d, 0xd2, 0x5d }, \
    }, \

(Source)

The parameters are explained here…

• “Device EUI, Join EUI and App Key”

Then edit lorawan_test_main.c at…

apps/examples/lorawan_test/lorawan_test_main.c

And set the LoRaWAN Frequency…

#ifndef ACTIVE_REGION
  #warning "No active region defined, LORAMAC_REGION_AS923 will be used as default."
  #define ACTIVE_REGION LORAMAC_REGION_AS923
#endif

(Source)

Which is explained here…

• “LoRaWAN Frequency”

Remember to disable all Info Logging because it affects the LoRaWAN Timers.

Rebuild (“make”) and reflash (“blflash”) NuttX to PineDio Stack.

In the NuttX Shell, enter this to run the LoRaWAN Test App…

lorawan_test

We should see this…

init_entropy_pool
temperature = 31.600670 Celsius

The app begins by reading BL604’s Internal Temperature Sensor to seed the Entropy Pool for the Random Number Generator. (Here’s why)

Next it sends a Join Network Request to the LoRaWAN Gateway (like ChirpStack)…

=========== MLME-Request ============
              MLME_JOIN              
=====================================
STATUS      : OK

Then the app receives the Join Accept Response from the LoRaWAN Gateway…

=========== MLME-Confirm ============
STATUS      : OK
===========   JOINED     ============
DevAddr     :  01097710
DATA RATE   : DR_2

After joining the network, the app sends a Data Packet (“Hi NuttX”) to the LoRaWAN Gateway…

=========== MCPS-Confirm ============
STATUS      : OK
=====   UPLINK FRAME        1   =====
CLASS       : A
TX PORT     : 1
TX DATA     : UNCONFIRMED
48 69 20 4E 75 74 74 58 00
DATA RATE   : DR_3
U/L FREQ    : 923200000
TX POWER    : 0
CHANNEL MASK: 0003

(See the complete log)

We should see “Hi NuttX” at the LoRaWAN Gateway (like ChirpStack)…

• “Check LoRaWAN Gateway”

For troubleshooting tips, see this…

• “Troubleshoot LoRaWAN”

Will PineDio Stack connect to The Things Network?

Yes just set the LoRaWAN Parameters like so…

• LORAWAN_DEVICE_EUI: Set this to the DevEUI from The Things Network

• LORAWAN_JOIN_EUI: Set this to { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 }

• APP_KEY, NWK_KEY: Set both to the AppKey from The Things Network

To get the DevEUI and AppKey from The Things Network…

• “Add Device to The Things Network”

(I don’t think NWK_KEY is used)

NuttX transmits a CBOR Payload to The Things Network Over LoRaWAN

§15.3 Test CBOR Encoder

Suppose we’re creating an app that transmits Sensor Data over LoRa (or LoRaWAN) from two sensors: Temperature Sensor and Light Sensor…

{ 
  "t": 1234, 
  "l": 2345 
}

(Located in a Greenhouse perhaps)

We could transmit 19 bytes of JSON. But there’s a more compact way to do it….

Concise Binary Object Representation (CBOR), which works like a binary, compressed form of JSON.

And we need only 11 bytes of CBOR!

To watch CBOR in action, enter this in the NuttX Shell…

tinycbor_test

We’ll see the encoded CBOR data…

test_cbor2: Encoding { "t": 1234, "l": 2345 }
CBOR Output: 11 bytes
  0xa2
  0x61
  0x74
  0x19
  0x04
  0xd2
  0x61
  0x6c
  0x19
  0x09
  0x29

(See the complete log)

To encode CBOR data in our own apps, check out this article…

• “Encode Sensor Data with CBOR on Apache NuttX OS”

CBOR Decoding can be done automatically in The Things Network…

• “CBOR Payload Formatter for The Things Network”

We can visualise the Sensor Data with open-source Grafana and Prometheus…

• “Monitor IoT Devices in The Things Network with Prometheus and Grafana”

§16 Appendix: Shared SPI Bus

This section explains how we modified NuttX to handle the Shared SPI Bus on PineDio Stack BL604.

Acording to the PineDio Stack Schematics…

• PineDio Stack Schematic (2021-09-15)

• PineDio Stack Baseboard Schematic (2021-09-27)

The SPI Bus is shared by…

• ST7789 Display Controller

• Semtech SX1262 LoRa Transceiver

• SPI Flash

Here are the BL604 GPIO Numbers for the shared SPI Bus…

(Source)

(See the GPIO Assignment)

To prevent crosstalk, we select each SPI Device by flipping its Chip Select Pin from High to Low…

(Source)

How is Chip Select implemented in NuttX?

To select (or deselect) an SPI Device, NuttX calls these functions provided by the BL602 / BL604 SPI Driver…

• bl602_spi_lock: Lock (or unlock) the SPI Bus with a Semaphore

• bl602_spi_select: Flip the Chip Select Pin to Low (or High)

However the SPI Driver doesn’t support multiple Chip Select Pins. (See this)

Here’s how we modded the SPI Driver for PineDio Stack…

§16.1 SPI Device ID

What’s the SPI Device ID in the table above?

We identify each SPI Device with a unique SPI Device ID.

NuttX passes the Device ID when it calls bl602_spi_select. We’ll use this to flip the right Chip Select Pin for the SPI Device.

How did we get the SPI Device IDs?

NuttX auto-assigns 0x40000 as the SPI Device ID for the ST7789 Display. (See this)

We assigned the other SPI Device IDs ourselves.

Device ID -1 is meant as a fallthrough to catch all SPI Devices that don’t match the Device IDs. This also works for simple SPI setups where the Device ID is not needed.

§16.2 Swap MISO / MOSI

What’s the Swap MISO / MOSI column in the table above?

According to the BL602 / BL604 Reference Manual (Table 3.1 “Pin Description”, Page 26)…

• GPIO 13 is designated as MOSI

• GPIO 0 is designed as MISO

But due to a BL602 / BL604 SPI quirk we need to swap MISO and MOSI to get this behaviour. (See this)

That’s why the “Swap MISO / MOSI” column is marked “Yes” for SX1262 Transceiver and SPI Flash.

But ST7789 doesn’t swap MISO and MOSI?

The ST7789 Display Controller is wired differently on PineDio Stack…

• ST7789 receives SPI Data on GPIO 0

• ST7789 Data / Command Pin is connected on GPIO 13

  (High for ST7789 Data, Low for ST7789 Commands)

The direction of SPI Data is flipped for ST7789.

That’s why the “Swap MISO / MOSI” column is marked “No” for the ST7789 Display Controller.

So we will swap and unswap MISO / MOSI on the fly?

Yep since we’ll run the ST7789, SX1262 and SPI Flash drivers concurrently, we’ll need to swap and unswap MISO / MOSI before every SPI operation.

We’ll do this in bl602_spi_select.

§16.3 SPI Device Table

How do we store the SPI Device Table in NuttX?

We represent the above SPI Device Table in NuttX as a flat int array…

(Source)

Here’s the source code for the SPI Device Table…

#ifdef CONFIG_BL602_SPI0
/* SPI Device Table: SPI Device ID, Swap MISO/MOSI, Chip Select */

static const int32_t bl602_spi_device_table[] =
{
#ifdef BOARD_LCD_DEVID  /* ST7789 Display */
  BOARD_LCD_DEVID, BOARD_LCD_SWAP, BOARD_LCD_CS,
#endif  /* BOARD_LCD_DEVID */

#ifdef BOARD_SX1262_DEVID  /* LoRa SX1262 */
  BOARD_SX1262_DEVID, BOARD_SX1262_SWAP, BOARD_SX1262_CS,
#endif  /* BOARD_SX1262_DEVID */

#ifdef BOARD_FLASH_DEVID  /* SPI Flash */
  BOARD_FLASH_DEVID, BOARD_FLASH_SWAP, BOARD_FLASH_CS,
#endif  /* BOARD_FLASH_DEVID */

  /* Must end with Default SPI Device */

  -1, 1, BOARD_SPI_CS,  /* Swap MISO/MOSI */
};
#endif  /* CONFIG_BL602_SPI0 */

(Source)

We’ll see the BOARD_* constants in the next section.

The columns of the SPI Device Table are defined like so…

/* Columns in the SPI Device Table */

#define DEVID_COL 0  /* SPI Device ID */
#define SWAP_COL  1  /* 1 if MISO/MOSI should be swapped, else 0 */
#define CS_COL    2  /* SPI Chip Select Pin */
#define NUM_COLS  3  /* Number of columns in SPI Device Table */

(Source)

We created these functions for accessing the SPI Device Table…

• bl602_spi_get_device: Lookup a device in the SPI Device Table

  (Called when selecting and deselecting devices)

• bl602_spi_deselect_devices: Deselect all devices in the SPI Device Table

  (Called during startup)

• bl602_spi_validate_devices: Validate the devices in the SPI Device Table

  (In case of coding errors)

Let’s look at the BOARD_* definitions.

§16.4 Pin Definitions

Where are the SPI Pins defined?

The SPI Device Table above refers to the following Pin Definitions at boards/risc-v/bl602/bl602evb/include/board.h

/* SPI for PineDio Stack: Chip Select (unused), MOSI, MISO, SCK */

#define BOARD_SPI_CS   (GPIO_INPUT | GPIO_PULLUP | GPIO_FUNC_SPI | GPIO_PIN8)  /* Unused */
#define BOARD_SPI_MOSI (GPIO_INPUT | GPIO_PULLUP | GPIO_FUNC_SPI | GPIO_PIN13)
#define BOARD_SPI_MISO (GPIO_INPUT | GPIO_PULLUP | GPIO_FUNC_SPI | GPIO_PIN0)
#define BOARD_SPI_CLK  (GPIO_INPUT | GPIO_PULLUP | GPIO_FUNC_SPI | GPIO_PIN11)

#ifdef CONFIG_LCD_ST7789
/* ST7789 for PineDio Stack: Chip Select, Reset and Backlight */

#define BOARD_LCD_DEVID SPIDEV_DISPLAY(0)  /* SPI Device ID: 0x40000 */
#define BOARD_LCD_SWAP  0    /* Don't swap MISO/MOSI */
#define BOARD_LCD_BL_INVERT  /* Backlight is active when Low */
#define BOARD_LCD_CS  (GPIO_OUTPUT | GPIO_PULLUP | GPIO_FUNC_SWGPIO | GPIO_PIN20)
#define BOARD_LCD_RST (GPIO_OUTPUT | GPIO_PULLUP | GPIO_FUNC_SWGPIO | GPIO_PIN3)
#define BOARD_LCD_BL  (GPIO_OUTPUT | GPIO_PULLUP | GPIO_FUNC_SWGPIO | GPIO_PIN21)
#endif  /* CONFIG_LCD_ST7789 */

/* SX1262 for PineDio Stack: Chip Select */

#define BOARD_SX1262_DEVID 1  /* SPI Device ID */
#define BOARD_SX1262_SWAP  1  /* Swap MISO/MOSI */
#define BOARD_SX1262_CS (GPIO_OUTPUT | GPIO_PULLUP | GPIO_FUNC_SWGPIO | GPIO_PIN15)

/* SPI Flash for PineDio Stack: Chip Select */

#define BOARD_FLASH_DEVID 2  /* SPI Device ID */
#define BOARD_FLASH_SWAP  1  /* Swap MISO/MOSI */
#define BOARD_FLASH_CS (GPIO_OUTPUT | GPIO_PULLUP | GPIO_FUNC_SWGPIO | GPIO_PIN14)

(GPIO, UART and I2C Pins are also defined in the file)

(See the GPIO Assignment)

Now that we have defined the SPI Device Table in NuttX, let’s use it.

§16.5 Select / Deselect SPI Device

Remember that NuttX calls bl602_spi_select to select (or deselect) an SPI Device.

For PineDio Stack, these are the changes we made to bl602_spi_select…

• NuttX already passes the SPI Device ID when it calls bl602_spi_select

• Based on the SPI Device ID, we look up the SPI Device Table

• We swap MISO and MOSI as specified by the SPI Device Table

• We flip the Chip Select Pin specified in the SPI Device Table

Here’s the implementation…

//  Enable/disable the SPI chip select
static void bl602_spi_select(struct spi_dev_s *dev, uint32_t devid,
                             bool selected)
{
  const int32_t *spidev;

  spiinfo("devid: %lu, CS: %s\n", devid, selected ? "select" : "free");

  /* get device from SPI Device Table */

  spidev = bl602_spi_get_device(devid);
  DEBUGASSERT(spidev != NULL);

  /* swap MISO and MOSI if needed */

  if (selected)
    {
      bl602_swap_spi_0_mosi_with_miso(spidev[SWAP_COL]);
    }

  /* set Chip Select */

  bl602_gpiowrite(spidev[CS_COL], !selected);

#ifdef CONFIG_SPI_CMDDATA
  /* revert MISO and MOSI from GPIO Pins to SPI Pins */

  if (!selected)
    {
      bl602_configgpio(BOARD_SPI_MISO);
      bl602_configgpio(BOARD_SPI_MOSI);
    }
#endif
}

(Source)

(bl602_gpiowrite is defined in the BL602 GPIO Driver)

(bl602_configgpio also comes from the BL602 GPIO Driver)

Let’s talk about CONFIG_SPI_CMDDATA…

§16.6 SPI Command / Data

NuttX RTOS uses MISO as the ST7789 Data / Command Pin. (See this)

(We flip the pin High for ST7789 Data, Low for ST7789 Commands)

But ST7789 is wired “backwards” on PineDio Stack BL604! We use MOSI as the ST7789 Data / Command Pin instead.

Here’s how we flip the ST7789 Data / Command pin depending on the “Swap MISO / MOSI” indicator in the SPI Device Table…

#ifdef CONFIG_SPI_CMDDATA
//  Called by NuttX to flip the ST7789 Data / Command Pin
static int bl602_spi_cmddata(struct spi_dev_s *dev,
                              uint32_t devid, bool cmd)
{
  spiinfo("devid: %" PRIu32 " CMD: %s\n", devid, cmd ? "command" :
          "data");

  if (devid == SPIDEV_DISPLAY(0))
    {
      const int32_t *spidev;
      gpio_pinset_t dc;
      gpio_pinset_t gpio;
      int ret;

      /* get device from SPI Device Table */

      spidev = bl602_spi_get_device(devid);
      DEBUGASSERT(spidev != NULL);

      /* if MISO/MOSI are swapped, DC is MISO, else MOSI */

      dc = spidev[SWAP_COL] ? BOARD_SPI_MISO : BOARD_SPI_MOSI;

      /* reconfigure DC from SPI Pin to GPIO Pin */

      gpio = (dc & GPIO_PIN_MASK)
             | GPIO_OUTPUT | GPIO_PULLUP | GPIO_FUNC_SWGPIO;
      ret = bl602_configgpio(gpio);
      if (ret < 0)
        {
          spierr("Failed to configure MISO as GPIO\n");
          DEBUGPANIC();

          return ret;
        }

      /* set DC to high (data) or low (command) */

      bl602_gpiowrite(gpio, !cmd);

      return OK;
    }

  spierr("SPI cmddata not supported\n");
  DEBUGPANIC();

  return -ENODEV;
}
#endif

(Source)

(bl602_configgpio is defined in the BL602 GPIO Driver)

(bl602_gpiowrite also comes from the BL602 GPIO Driver)

Note that we reconfigure MISO / MOSI from SPI Pins to GPIO Pins.

We revert MISO / MOSI back to SPI Pins when the SPI Device is deselected in bl602_spi_select.

§16.7 Deselect All SPI Devices

At NuttX Startup, we deselect all SPI Devices by flipping their Chip Select Pins high (after validating the SPI Device Table)…

//  Called by NuttX to initialise the SPI Driver
static void bl602_spi_init(struct spi_dev_s *dev)
{
  /* Omitted: Init SPI port */
  ...
  /* spi fifo clear */

  modifyreg32(BL602_SPI_FIFO_CFG_0, SPI_FIFO_CFG_0_RX_CLR
              | SPI_FIFO_CFG_0_TX_CLR, 0);

  /* deselect all spi devices */

  bl602_spi_deselect_devices();
}

(Source)

(bl602_spi_deselect_devices is defined here)

§16.8 Test Shared SPI Bus

But will this Shared SPI Bus work? Swapping MISO / MOSI on the fly while flipping multiple Chip Select Pins?

Yes the Shared SPI Bus works beautifully on PineDio Stack! This is how we tested with ST7789 Display and SX1262 Transceiver…

1. We boot PineDio Stack, which calls the ST7789 Driver to render a Pink Screen…

   (Our SPI Driver unswaps MISO / MOSI, flips ST7789 Chip Select)

   board_lcd_getdev: SPI port 0 bound to LCD 0
   st7789_getplaneinfo: planeno: 0 bpp: 16

   (See the complete log)

2. Then we run the spi_test2 app to read a SX1262 Register over SPI…

   (Our SPI Driver swaps MISO / MOSI, flips SX1262 Chip Select)

   nsh> spi_test2
   ...
   Read Register 8: received
   a2 a2 a2 a2 80
   SX1262 Register 8 is 0x80

   (See the complete log)

   SX1262 returns Register Value 0x80, which is correct!

3. Finally we run the LVGL Demo App to access the ST7789 Display…

   (Our SPI Driver unswaps MISO / MOSI, flips ST7789 Chip Select)

   nsh> lvgldemo
   st7789_getvideoinfo: fmt: 11 xres: 240 yres: 240 nplanes: 1
   lcddev_init: VideoInfo:
     fmt: 11
     xres: 240
     yres: 240
     nplanes: 1
   ...
   monitor_cb: 57600 px refreshed in 1110 ms

   (See the complete log)

   Which renders the LVGL Demo Screen correctly!

§16.9 ST7789 SPI Mode

BL602 / BL604 has another SPI Quirk that affects ST7789 on PineDio Stack…

BL602 / BL604 talks to ST7789 Display at SPI Mode 1 or Mode 3, depending on whether MISO / MOSI are swapped…

• If MISO / MOSI are NOT Swapped:

  Use SPI Mode 1

• If MISO / MOSI are Swapped:

  Use SPI Mode 3

Since MISO / MOSI are not swapped for ST7789 on PineDio Stack, we use SPI Mode 1. Here’s the implementation…

#ifdef CONFIG_BL602_SPI0
#include "../boards/risc-v/bl602/bl602evb/include/board.h"
#endif  /* CONFIG_BL602_SPI0 */

//  If ST7789 is enabled...
#ifdef CONFIG_LCD_ST7789

//  If this is BL602...
#ifdef CONFIG_BL602_SPI0

  //  If MISO/MOSI are not swapped...
  #if defined(BOARD_LCD_SWAP) && BOARD_LCD_SWAP == 0
    //  Use SPI Mode 1 as workaround for BL602
    #warning Using SPI Mode 1 for ST7789 on BL602 (MISO/MOSI not swapped)
    #define CONFIG_LCD_ST7789_SPIMODE SPIDEV_MODE1

  //  If MISO/MOSI are swapped...
  #else
    //  Use SPI Mode 3 as workaround for BL602
    #warning Using SPI Mode 3 for ST7789 on BL602 (MISO/MOSI swapped)
    #define CONFIG_LCD_ST7789_SPIMODE SPIDEV_MODE3
  #endif /* BOARD_LCD_SWAP */

//  If this is not BL602...
#else

  //  Use the SPI Mode specified in menuconfig
  #ifndef CONFIG_LCD_ST7789_SPIMODE
  #define CONFIG_LCD_ST7789_SPIMODE SPIDEV_MODE0
  #endif   /* CONFIG_LCD_ST7789_SPIMODE */

#endif   /* CONFIG_BL602_SPI0 */

(Source)

Note that we have configured PineDio Stack to talk to SX1262 at SPI Mode 1 via the SPI Test Driver “/dev/spitest0”. (See this)

§16.10 ST7789 SPI Frequency

We have configured the SPI Frequency of the ST7789 Display to 40 MHz, the maximum supported by BL604…

CONFIG_LCD_ST7789_FREQUENCY=4000000

(Source)

We configured the SPI Frequency in menuconfig at…

• Device Drivers → LCD Driver Support → Graphic LCD Driver Support → LCD Driver Selection → Sitronix ST7789 → SPI Frequency

In future we should implement SPI with Direct Memory Access (DMA) to avoid busy-polling the SPI Bus. (See this)

Hopefully this will improve the responsiveness of the touchscreen.

UPDATE: SPI DMA is now supported on BL602 / BL604 NuttX…

• “SPI DMA on BL602 NuttX”

§16.11 SX1262 Chip Select

There’s a potential Race Condition if we use the SX1262 Driver concurrently with the ST7789 Driver…

• During LoRa Transmission, SX1262 Driver calls ioctl() to flip SX1262 Chip Select to Low

  (See this)

• SX1262 Driver calls SPI Test Driver “/dev/spitest0”, which locks (SPI_LOCK) and selects (SPI_SELECT) the SPI Bus (with SPI Device ID 0)

  (See this)

• Note that the calls to ioctl() and SPI_LOCK / SPI_SELECT are NOT Atomic

• If the ST7789 Driver is active between the calls to ioctl() and SPI_LOCK / SPI_SELECT, both SX1262 Chip Select and ST7789 Chip Select will be flipped to Low

• This might transmit garbage to SX1262

To solve this problem, we will register a new SPI Test Driver “/dev/spitest1” with SPI Device ID 1. (With some tweaks to the driver code)

The LoRa Driver will be modified to access “/dev/spitest1”, which will call SPI_LOCK and SPI_SELECT with SPI Device ID 1.

Since the SPI Device ID is 1, SPI_SELECT will flip the SX1262 Chip Select to Low.