In this post, I will show you how to flash an Android OS image on an Orange Pi 5B board using a Linux host.

Though it’s not as straightforward as it might seem.

The Challenge

The Orange Pi 5B manual mentions that building its Android based OS, needs to be done on a Linux host.

The build output is an update.img file that is possible to flash to the Orange Pi 5B device using the Windows only methods, through a TF card or a Type-C cable into eMMC.

The proposed approach in the manual for flashing is using different Windows compatible applications, such as RKDevTool or SDDiskTool.

This approach of building the OS on Linux, but can only be flashed using Windows, is an annoying approach as it requires a constant switch between the Linux and the Windows operating systems. Which is very time-consuming and significantly affects the feedback cycle.

I’ve also tried using Windows’ WSL for the build process, but it wasn’t able to install part of the required packages.

The rkdevelop Tool

The Orange Pi 5B has a Rockchip SoC, and Rockchip provides a tool called rkdeveloptool which allows flashing OS images to the device.

The issue was that I couldn’t find any information on how to use this tool to flash an Android OS image to the Orange Pi 5B device, or any similar information.

To install the rkdeveloptool on Ubuntu, I’ve used the following commands:

sudo apt-get update
sudo apt-get install -y libudev-dev libusb-1.0-0-dev dh-autoreconf pkg-config libusb-1.0 build-essential git wget
git clone https://github.com/rockchip-linux/rkdeveloptool
cd rkdeveloptool
wget https://patch-diff.githubusercontent.com/raw/rockchip-linux/rkdeveloptool/pull/73.patch
wget https://patch-diff.githubusercontent.com/raw/rockchip-linux/rkdeveloptool/pull/85.patch
git am *.patch
autoreconf -i
./configure
make -j $(nproc)

The loader file

Before it is possible to flash the OS image to the Orange Pi 5B device, it is necessary to flash a loader file to the device.

The loader file could be found here: Orange Pi 5B loader file. This file is used to boot the device into a mode where it is possible to flash the OS image to it.

It will be loaded as part of the flashing process. Command details will be provided in the next chapters.

The Flashing Process

As part of building the Android OS, there are several images that are created:

1. uboot.img
2. misc.img
3. dtbo.img
4. vbmeta.img
5. boot.img
6. recovery.img
7. baseparameter.img
8. super.img

As part of the build process they all are combined into a single update.img file using RKImageMaker tool. It is done automatically by the build process, so we don’t need to worry about it.

Each image has its own responsibility and is flashed to a specific address on the device. I might cover the responsibilities of each image in a separate post.

For now we just need to know that we need all of them to flash the OS to the device.

On Windows the flashing process is described in detail in the Orange Pi 5B manual. But there is no description on how to flash the Android OS on a Linux host.

Fortunately we can look at the logs of the Windows flashing process and see that behind the scenes the Windows tool is splitting the update.img back to the individual images and flashing them to the device one by one using specific addresses.

I found out the following addresses for each image:

1. uboot.img - 0x4000
2. misc.img - 0x9000
3. dtbo.img - 0xb000
4. vbmeta.img - 0xd000
5. boot.img - 0xd800
6. recovery.img - 0x3f800
7. baseparameter.img - 0x1f7800
8. super.img - 0x1f8000

Now using the rkdeveloptool we can flash the images to the device. Example command for flashing the uboot.img to the device:

sudo rkdeveloptool wl 0x4000 uboot.img

The Full Process

So basically the full process is pretty simple. After building the Android OS we need to do the following steps:

1. Put the device into maskrom mode - This is done by holding the maskrom button on the board while powering the device on.
2. Flash the loader file to the device - sudo rkdeveloptool db rk3588_spl_loader_v1.15.113.bin
3. Flash the individual images to the device using specific addresses - sudo rkdeveloptool wl <address> <image_path>
4. Reboot the device - sudo rkdeveloptool rd

After that the device should boot into the flashed Android OS.

I’ve also prepared a bash script that automates the flashing process, which also does some basic validations before it starts the flashing process.

The full script:

#!/bin/bash

# Check if the correct number of arguments is provided
if [ "$#" -ne 1 ]; then
    echo "Usage: $0 <folder_path>"
    exit 1
fi

# Set the folder path from the input parameter
FOLDER_PATH=$1

# Check if the folder exists
if [ ! -d "$FOLDER_PATH" ]; then
    echo "Error: Folder '$FOLDER_PATH' does not exist."
    exit 1
fi

# the loader file should be located in the current directory.
LOADER="$(pwd)/rk3588_spl_loader_v1.15.113.bin"

# Define the images and their offsets
declare -A IMAGES=(
    [uboot.img]=0x4000
    [misc.img]=0x9000
    [dtbo.img]=0xb000
    [vbmeta.img]=0xd000
    [boot.img]=0xd800
    [recovery.img]=0x3f800
    [baseparameter.img]=0x1f7800
    [super.img]=0x1f8000
)

# Check if the loader file exists
if [ ! -f "$LOADER" ]; then
    echo "Error: Loader file '$LOADER' does not exist."
    exit 1
fi

# Check if a device in Maskrom mode is connected
DEVICE_INFO=$(sudo rkdeveloptool ld | grep "Maskrom")

if [ -z "$DEVICE_INFO" ]; then
    echo "No device in Maskrom mode detected. Please connect the device and ensure it is in Maskrom mode."
    exit 1
else
    echo "Device in Maskrom mode detected: $DEVICE_INFO"
fi

# Check if all required image files are available
for IMAGE in "${!IMAGES[@]}"; do
    IMAGE_PATH="$FOLDER_PATH/$IMAGE"
    if [ ! -f "$IMAGE_PATH" ]; then
        echo "Error: Required image file '$IMAGE_PATH' is missing."
        exit 1
    fi
done

echo "All required image files are present."

# Load the loader
echo "Loading the loader from $LOADER..."
sudo rkdeveloptool db $LOADER

# Flash each image
for IMAGE in "${!IMAGES[@]}"; do
    OFFSET=${IMAGES[$IMAGE]}
    IMAGE_PATH="$FOLDER_PATH/$IMAGE"
    
    # Check if the image file exists
    if [ -f "$IMAGE_PATH" ]; then
        echo "Flashing $IMAGE at offset $OFFSET..."
        sudo rkdeveloptool wl $OFFSET $IMAGE_PATH
    else
        echo "Warning: Image file '$IMAGE_PATH' not found, aborting."
        exit 1
    fi
done

# Reboot the device
echo "Rebooting the device..."
sudo rkdeveloptool rd

echo "Flashing process completed."

Conclusion

Now after we are able to flash the Android OS on a Linux host, the feedback cycles are much faster and the development process is much smoother. In my experience, it has reduced my cognitive load and allowed me to focus more on the development process itself, and solving the actual problems, rather than wasting a lot of time on switching between the operating systems and remembering what I was doing and what I wanted to do.

Thanks for reading.

In my recent project, I aimed to visualize data from a Bluetooth Low Energy (BLE) device, a task that required integrating different technologies. The bleak library was my choice for managing BLE communications in Python, known for its robust support for these devices.

The challenge arose when I wanted to plot this data using matplotlib, a library that excels in data visualization but operates synchronously. Since bleak operates asynchronously, I faced the task of finding a way to bridge these two different operational modes.

matplotlib, while powerful, necessitates execution on the main thread—a requirement that complicates its use with asynchronous data streams like those from bleak. This scenario highlighted a common issue in software development: integrating synchronous and asynchronous systems in a seamless manner.

Solution

To address the challenge of integrating asynchronous data reception with synchronous plotting, I devised a solution that involves running the asyncio event loop in a separate thread, while executing the plotting operations on the main thread.

Here’s an overview of how I implemented this approach:

The key to this setup was utilizing zmq to simulate the data communication between the BLE device and the plotting application. For this, the aiozmq library provided the necessary asynchronous support for zmq communication.

You can find the complete implementation in my GitHub repository: async-plotting.

Let’s briefly discuss the code structure:

First, we establish a new event loop and run it in a background thread, allowing the main thread to handle plotting:

def run_event_loop(loop):
    asyncio.set_event_loop(loop)
    loop.run_until_complete(main())


if __name__ == '__main__':
    new_loop = asyncio.new_event_loop()
    t = threading.Thread(target=run_event_loop, args=(new_loop,))
    t.start()
    plotter()
    t.join()

Within the new event loop, zmq communication handles both publishing and subscribing tasks concurrently:

async def main():
    publisher_task = asyncio.create_task(publish_messages())
    subscriber_task = asyncio.create_task(subscribe_to_messages(update_data))

    await asyncio.gather(publisher_task, subscriber_task)

The subscriber receives messages and updates the plotting data through a callback (update_data), which queues the data for plotting:

plotting_queue = Queue()


def update_data(data: bytes):
    plotting_queue.put(int(data.decode('utf-8')))

Finally, the plotter function, running on the main thread, continuously reads from the queue and updates the plot:

def plotter():
    plt.ion()
    fig, ax = plt.subplots()
    x_data, y_data = [], []

    while True:
        if not plotting_queue.empty():
            message_int = plotting_queue.get()
            x_data.append(len(x_data))
            y_data.append(int(message_int))
            ax.clear()
            ax.plot(x_data, y_data)
            plt.draw()
            plt.pause(0.1)
        plt.pause(0.1)  # Small pause to prevent busy waiting.

This method uses plt.ion() for interactive plotting and periodic pauses to ensure the GUI remains responsive and the plot updates smoothly.

Conclusion

The technique outlined here is adaptable and can serve as a blueprint for similar asynchronous data visualization tasks. It highlights Python’s flexibility in addressing complex programming scenarios, offering a straightforward path for those looking to balance asynchronous data streams with real-time plotting.

Welcome to an exciting chapter in the journey of Strikeco, where innovation meets the world of tennis simulation. At Strikeco, we’re not just creating tennis simulators; we’re redefining the very essence of interactive sports technology. Our mission is to blend cutting-edge hardware with seamless software integration to bring you the future of tennis experiences.

In this blog post, we’ll dive into our latest exploration with the OrangePi 5B SBC. This piece of technology has emerged as a frontrunner in our pursuit of performance excellence and user-friendly design. As we navigate through the intricacies of hardware optimization, each step brings us closer to designing a custom SBC tailored perfectly for our final product.

Join us on this adventure, as we share our insights and breakthroughs with the OrangePi 5B. Whether you’re a tech enthusiast, a tennis aficionado, or simply curious about our process, there’s something here for everyone. We’re excited to give you a behind-the-scenes look at how we’re pushing the boundaries of tennis simulation technology at Strikeco.

Overview

Recently, our team embarked on an innovative project, bridging the gap between hardware and software: we are developing a custom D-pad controller for a Unity-based game, tailored to run seamlessly on a Single Board Computer (SBC). Our hardware of choice for testing? The robust and cost-effective OrangePI.

For the operating system, we chose Android OS, a decision influenced by its seamless compatibility and impressive performance alongside the Unity game engine.

While the specifics of the game itself are intriguing, this blog post will primarily focus on the technical side of things. Specifically, we’ll explore how to handle GPIOs on the OrangePI Android OS and how this functionality can be integrated within a Unity game.

Join us at Strikeco as we delve into the intricacies of integrating physical game controls with advanced software. We’ll be sharing our insights and practical steps, guiding anyone interested in undertaking a similar endeavor in their Unity projects, especially those involving unconventional gaming setups.

OrangePi Background

In our search for the ideal SBC for this project, we chose the OrangePi 5B. This decision was based on its impressive performance capabilities — in terms of both CPU and GPU — and its cost-effectiveness.

The OrangePi 5B is equipped with two 4-core CPUs and the ARM Mali-G610 GPU, a combination that offers substantial power for demanding applications. This power is further complemented by an onboard NPU, an exciting feature that opens doors for future projects, potentially involving advanced computing tasks like machine learning.

Another appealing aspect of the OrangePi 5B is its integrated WIFI and Bluetooth functionality. This not only allows for versatile communication options with the device but also paves the way for interesting future explorations in wireless connectivity.

The board typically runs OrangePi OS (Druid), an Android-based operating system. This was a pivotal factor in our decision, as we were planning to develop a game using Unity. The Android platform is renowned for its compatibility with Unity, which we anticipated would ensure a smoother development process and optimal performance for our game.

In summary, the OrangePi 5B emerged as an excellent choice for us — a robust, feature-rich board that’s competitively priced. It perfectly suits our current project requirements and offers great potential for future experimentation and development.

WiringOP

WiringOP is a pre-installed Android application on the OrangePi Android OS, serving as a gateway to exploring the physical pins of the SBC. It provides functionalities to read and write to these pins, offering a visual representation of their states.

One notable feature of the WiringOP app is a button that displays the state of all the pins, essentially mirroring the output of the command-line instruction gpiox readall. The resulting display looks something like this:

+------+-----+----------+------+---+  OPi H6  +---+------+----------+-----+------+
 | GPIO | wPi |   Name   | Mode | V | Physical | V | Mode | Name     | wPi | GPIO |
 +------+-----+----------+------+---+----++----+---+------+----------+-----+------+
 |      |     |     3.3V |      |   |  1 || 2  |   |      | 5V       |     |      |
 |  230 |   0 |    SDA.1 |  OFF | 0 |  3 || 4  |   |      | 5V       |     |      |
 |  229 |   1 |    SCL.1 |  OFF | 0 |  5 || 6  |   |      | GND      |     |      |
 |  228 |   2 |     PWM1 |  OFF | 0 |  7 || 8  | 0 | OFF  | PD21     | 3   | 117  |
 |      |     |      GND |      |   |  9 || 10 | 0 | OFF  | PD22     | 4   | 118  |
 |  120 |   5 |    RXD.3 | ALT4 | 0 | 11 || 12 | 0 | OFF  | PC09     | 6   | 73   |
 |  119 |   7 |    TXD.3 | ALT4 | 0 | 13 || 14 |   |      | GND      |     |      |
 |  122 |   8 |    CTS.3 |  OFF | 0 | 15 || 16 | 0 | OFF  | PC08     | 9   | 72   |
 |      |     |     3.3V |      |   | 17 || 18 | 0 | OFF  | PC07     | 10  | 71   |
 |   66 |  11 |   MOSI.0 | ALT4 | 0 | 19 || 20 |   |      | GND      |     |      |
 |   67 |  12 |   MISO.0 | ALT4 | 0 | 21 || 22 | 0 | OFF  | RTS.3    | 13  | 121  |
 |   64 |  14 |   SCLK.0 | ALT4 | 0 | 23 || 24 | 0 | ALT4 | CE.0     | 15  | 69   |
 |      |     |      GND |      |   | 25 || 26 | 0 | OFF  | PH03     | 16  | 227  |
 +------+-----+----------+------+---+----++----+---+------+----------+-----+------+
 | GPIO | wPi |   Name   | Mode | V | Physical | V | Mode | Name     | wPi | GPIO |
 +------+-----+----------+------+---+  OPi H6  +---+------+----------+-----+------+

From this table, two columns are particularly important: wPi and V. The wPi number is crucial for interacting with the pins through software, as it’s used to reference a pin’s state. The V column, on the other hand, indicates whether current is flowing through a pin, which is vital for setting or resetting it.

After our team experimented with WiringOP, we realized that if the app could read and write to the pins, we should be able to replicate this functionality in our Android application. But how to achieve this was not immediately obvious.

Our initial search for resources and discussions online didn’t yield straightforward answers. Consequently, we took a more direct approach: delving into the source code of WiringOP itself. Discovering that WiringOP came pre-installed with OrangePi OS led us to believe it was bundled with the operating system. This spurred our team to delve into the depths of OrangePI’s Android OS source code, aiming to uncover the mechanisms behind WiringOP’s functionality.

OrangePi Android OS

In our endeavor to establish a connection between our Android Kotlin code and the GPIO pins on the OrangePi board, we initially considered exploring the WiringOP GitHub repository. This approach, however, proved challenging as the repository lacked clear instructions for compiling the code for Android integration, and we found no further insights in the issues section.

Confronted with limited options, our team decided to delve directly into the OrangePi Android OS source code, available on their official website. The source code is split into several tar.gz files, all housed on their Google Drive under the RK3588S_Android_Source_Code directory.

To start working with the code, the first step is to combine and extract these files. This involves:

1. Combining the files into a single archive: cat Android_12.tar.gz* > Android_12.tar.gz
2. Extracting the contents: tar -xvf Android_12.tar.gz

For Windows users, the Cygwin tool can provide the necessary tar command. Be prepared, as the extraction process is quite time-consuming and requires patience.

Once the extraction was complete, we began our search for the WiringOP application. As anticipated, it was located in the packages/apps/WiringOP directory. Here, not only is the application’s source code present, but also, crucially, the C source code of WiringOP, similar to what’s seen on GitHub. The key difference here is the presence of several Android.mk files – absent in the GitHub repository – which are essential for building the required libraries and files for any Android application looking to access the GPIOs on the board.

In the following section, we will take a closer look at these components to understand what is required for our project and how we can effectively utilize them.

WiringOP Internals

In the heart of the WiringOP application lies the process of building the necessary libraries – the .so files. The most straightforward method we found involves using Android Studio. Open the packages/apps/WiringOP directory in Android Studio and navigate to the com.example.demo.MainActiviy file. From there, execute the Build->Make Module 'wiringOp.app.main' command.

This process generates an .apk file, specifically app-debug.apk, located in the build/outputs/apk/debug/ folder. The compiled libraries we need are tucked inside this .apk, under the lib folder. Within, you’ll find two subfolders: armeabi-v7a and arm64-v8a, each corresponding to a different ARM architecture. For our project, we chose arm64-v8a. This involved incorporating the entire folder into our Android project, specifically under the src/main/jniLibs/ directory.

Having successfully built the WiringOP libraries, the next step is to establish a communication interface with them. In the WiringOP app, under the com.example.wiringop package, there’s a crucial file named wpiControl. It’s a class filled with static methods enabling interaction with the WiringOP libraries.

An important note here: when integrating wpiControl into your application, it’s essential to retain its original package structure, i.e., com.example.wiringop. While not aesthetically pleasing, this is necessary for the JNI (Java Native Interface) to locate the functions in the libraries. While it might be feasible to modify this using tools like javac -h, we didn’t explore this option for our current project.

Before integrating the wpiControl class into our application, there is an essential step to consider. The WiringPi library maps the memory directly to the pins, necessitating read and write permissions to the physical memory of the OrangePi device. This is achieved by executing chmod 666 /dev/mem before calling the wiringPiSetup() method. The most practical way to run this command is at your application’s startup.

A word of caution: the chmod 666 command sets permissions that are not secure, especially for a production environment. While this approach was suitable for our initial testing, we recommend caution and encourage further research into more secure alternatives, especially in different or more extensive project contexts.

Now, let’s discuss how we integrate and utilize the wpiControl class in our Android application.

Our Project

So far in this post, I’ve referenced our project several times, and it’s time to delve deeper into its specifics. The project is a Unity game controlled by a D-pad, designed to run on the OrangePi5b with Android OS.

The aim was to make the D-pad function like a standard Android D-pad, recognized and handled by Unity without needing custom event monitoring. To achieve this, we utilized the Android input CLI command to simulate key presses.

Incorporating this functionality into Unity required creating an Android plugin. This plugin is essentially an Android module containing the compiled libraries and the wpiControl class from WiringOP, which interacts with the GPIOs and executes the input command.

The plugin works by starting a thread that constantly checks the GPIO pins. When it detects a button press on the D-pad, it triggers the corresponding input command to simulate a D-pad key press in Unity.

Here is an example command for simulating a DPAD_UP key press:

input keyevent 19

We based our key simulations on the KEYCODE_DPAD_* constants found in the android.view.KeyEvent class of the Android SDK. The Android plugin was developed in Android Studio as an Android Library module, where we included the necessary arm64-v8a libraries and the wpiControl class.

For creating an Android plugin, we just need to create a new project in Android Studio, and create a new module of Android Library type.

Copy the arm64-v8a folder under the src/main/jniLibs/ folder (create the jniLibs folder if it doesn’t exist).

Copy the wpiControl file, under the src/main/java/ folder into the com.example.wiringop package.

The core of the plugin is the UnityEntrypoint class, which handles GPIO reading and triggers key events:

class UnityEntrypoint() {
    // The thread that will run our GPIO handling loop.
    private var executor = Executors.newSingleThreadExecutor()

    // This will start the main GPIO loop that handles reading from the pins and invoking the relevant key
    fun start() {
        if (executor.isShutdown)
            executor = Executors.newSingleThreadExecutor()
        executor.execute {
            mainGpioLoop()
        }
    }

    private fun mainGpioLoop() {
        // Prepare the necessary things for using the wiringPi library to read GPIOs.
        runRootCommand("chmod 666 /dev/mem")
        wpiControl.wiringPiSetup()

        // All the D-Pad related pins should be in the IN mode.
        initializeDpadKeysPins()

        // Start looping and handling GPIOs
        while (!Thread.currentThread().isInterrupted) {
            handleKeysPress()
            Thread.sleep(100) // Wait a bit before continuing to read from GPIOs.
        }
    }

    private fun initializeDpadKeysPins() {
        dpadKeyPins.forEach { (_, pin) -> 
            wpiControl.pinMode(pin, 0)
        }
    }

    private fun handleKeysPress() {
        dpadKeyPins.forEach { (key, pin) -> 
            val pinValue = wpiControl.digitalRead(pin)
            if (pinValue == 0) {
                invokeKey(key)
            }
        }
    }

    private fun invokeKey(dpadKey: DpadKey) {
        val keyCode = when (dpadKey) {
            DpadKey.UP -> KeyEvent.KEYCODE_DPAD_UP
            DpadKey.DOWN -> KeyEvent.KEYCODE_DPAD_DOWN
            DpadKey.LEFT -> KeyEvent.KEYCODE_DPAD_LEFT
            DpadKey.RIGHT -> KeyEvent.KEYCODE_DPAD_RIGHT
            DpadKey.ENTER -> KeyEvent.KEYCODE_ENTER
        }
        val cmd = "input keyevent $keyCode"
        // This is a simplified approach, it might be better to also catch exceptions and print the output of the command to catch errors.
        val process = Runtime.getRuntime().exec(cmd)
        process.waitFor()
    }

    // This is basically running a command after switching to the root user.
    private fun runRootCommand(cmd: String) {
        // Please note that it is a simplified example, and we might need to aslo implement output printing and exception handling.
        val process = Runtime.getRuntime().exec("su")
        val dos = DataOutputStream(process.outputStream)
        dos.writeBytes("$cmd\n")
        dos.flush()
        dos.writeBytes("exit\n")
        dos.flush()
        process.waitFor()
        dos.close()
    }

    // Stops the thread
    fun stop() {
        executor.shutdown()
    }

    companion object {
        enum class DpadKey {
            UP,
            DOWN,
            LEFT,
            RIGHT,
            ENTER
        }

        // Here we should adjust the pin numbers, to correspond to the D-Pad buttons.
        val dpadKeyPins = mapOf(
            DpadKey.UP to 4,
            DpadKey.DOWN to 9,
            DpadKey.LEFT to 6,
            DpadKey.RIGHT to 3,
            DpadKey.ENTER to 10
        )
    }
}

Building this module in Android Studio generates an .aar file, located in the build/outputs/aar/ folder. This file is then integrated into the Unity project, a process we will describe in the next section.

Unity

With our Android plugin now ready, the next step is to integrate it into our Unity game. Unity handles Android plugins through the AndroidJavaObject, a powerful interface for interacting with Java objects. More information on this can be found in the Unity documentation.

The key is to create a C# class within Unity that initializes and controls the UnityEntrypoint class we developed in the Android plugin. This class will manage the starting and stopping of our GPIO listening loop.

Here’s an example of how this can be implemented in Unity:

public class AndroidInputSimulator {
    private AndroidJavaObject _plugin;

    public void Start() {
        // Initialize the Android plugin
        _plugin = new AndroidJavaObject("our.package.UnityEntrypoint");
        // Start the GPIO loop
        _plugin.Call("start");
    }

    public void Stop() {
        // Stop the GPIO loop
        _plugin?.Call("stop");
    }
}

This AndroidInputSimulator class can be used anywhere in our Unity game to start listening to GPIO inputs. When the Start method is called, it initiates the mainGpioLoop in a separate thread on the Android device, which listens for GPIO changes and simulates key presses. These simulated key presses are then recognized by Unity’s input system as if they were regular key presses.

To build the game’s .apk file for deployment, we need to adjust a few settings in Unity’s player settings under the Android tab. Specifically, in the Configuration section, make the following updates:

Scripting Backend = IL2CPP
Target Architectures = ARM64 (only)

The ARM64 architecture setting is crucial because our Android library is built for arm64-v8a. The IL2CPP scripting backend is required since Unity cannot use ARM64 with the mono backend.

With these settings configured, you can now build and run the .apk on your device, and the game should respond to the D-pad inputs as intended.

Conclusion

In this post, we’ve journeyed through the intricate process of integrating a custom D-pad controller with a Unity game on an OrangePI SBC running Android OS. Let’s briefly recap the key steps we undertook:

1. Choosing the Hardware: We started by selecting the OrangePI 5B for its impressive performance and cost-effectiveness, coupled with its compatibility with Android OS – a prime choice for Unity game development.

2. Exploring WiringOP: We delved into the WiringOP application, which offered a gateway to interact with the GPIOs on the OrangePI. This involved understanding its functionality and the crucial wPi and V columns in its GPIO table.

3. Diving into OrangePI’s Android OS: Faced with limited resources online, we explored the OrangePI Android OS source code to understand and replicate the functionality of WiringOP in our own Android application.

4. Building the Android Plugin: We created an Android plugin in Android Studio, incorporating the WiringOP libraries and the wpiControl class. This plugin was essential in reading GPIO inputs and simulating key presses using the input CLI command.

5. Integrating with Unity: In Unity, we used the AndroidJavaObject to integrate our Android plugin, allowing us to control the game with the custom D-pad. We also discussed the necessary Unity player settings for building the game’s .apk file.

As we look to the future, one promising avenue to explore is integrating this custom D-pad setup with Unity’s new Input System. This modern, flexible system offers more options for input configuration and might provide an even smoother integration process and enhanced gameplay experience. It’s an exciting prospect for further enhancing the interactivity of games on platforms like OrangePI.

Embarking on a project that intertwines hardware and software aspects can be challenging but equally rewarding. Through this journey, we’ve seen how creativity and perseverance can lead to innovative solutions, broadening the horizons of what’s possible in game development and hardware interaction.

Overview

My overall plan in implementing the go/links solution was to validate that I’m able to route requests to the webserver from the browser and that it would redirect my request to some website, and I will get the result in the browser.

I wanted to make that validation as fast as possible, so I wanted to start with the most basic and simple webserver that I can build. For that I went with FastApi, and created a very basic webserver.

Some TDD

Lately I’ve started using the TDD (Test Driven Development) process more often. As I saw that it helps me to design pretty good applications, and also add some tests that would allow to refactor the code later with a peace of mind, as I already had tests to cover the areas that I change and still be somewhat sure that the behavior is correct.

I’ve created a project library, added there the following requirements.txt:

fastapi==0.72
uvicorn[standard]==0.17
requests==2.27.1
pytest==6.2.5

Created a virtual environment and installed the requirements there.

From there I’ve started with the tests, instead of starting with the implementation of the webserver.

I’ve created two tests that would describe the behavior that I wanted from my basic webserver at this stage of the project. The tests were:

def test_get_link_not_found():
    ...

def test_get_links_no_links():
    ...

In the first test, I test what should happen if a link was requested but it wasn’t found.

And in the second test I make sure that a GET ALL links request returns an empty list of links.

These behaviors are good enough behaviors to see that the webserver sends some responses.

Filling those tests using the FastAPI test example was pretty easy. The whole file eventually looked like this:

from fastapi.testclient import TestClient
from golinks.main import app

client = TestClient(app)


def test_get_link_not_found():
    response = client.get('/links/non_existent_link')
    assert response.status_code == 404
    assert response.json() == {'detail': 'Link non_existent_link not found'}


def test_get_links_no_links():
    response = client.get('/links')
    assert response.status_code == 200
    assert response.json() == {'links': []}

At this point of course the tests couldn’t run, as we didn’t have some of the components specifically the app. But we already had some tests, and we knew what was missing, so we can now create our webserver (the app).

Creating a FastAPI app is a breeze, we just need to instantiate it, like so:

from fastapi import FastAPI

app = FastAPI()

And now we just need to add the endpoints that we need, such as endpoints for:

1. Fetching all the links
2. Fetching specific information about a link

The whole code for the webserver for now is as follows:

from fastapi import FastAPI, HTTPException

app = FastAPI()


@app.get('/links')
def get_all_links():
    return {'links': []}


@app.get('/links/{link_id}')
def get_link(link_id: str):
    raise HTTPException(status_code=404, detail=f'Link {link_id} not found')

We can see that we allow two endpoints a /links/ and a /links/{link_id}. The first one is without a parameter and we expect it to return all the links that we have stored in the database, but for now we have nothing, as we don’t even have a database, so it just returns an empty list of links.

The second one is the one that should just return information about the link. But because we still haven’t implemented any storage for that and we for sure have no links to return, it just raises a not found HTTP status code.

Now we can run our tests and see if they work as expected using pytest like that:

PYTHONPATH=. pytest

And we can even run the webserver and query it by running:

uvicorn golinks.main:app

By default, it should bind the webserver to port 8000, so sending requests to it should return the expected results. For example:

curl -v http://127.0.0.1:8000/links/some_link

...
< HTTP/1.1 404 Not Found
...
{"detail":"Link some_link not found"}

Or if trying the /links endpoint:

curl http://127.0.0.1:8000/links
 
{"links":[]}

Next Steps

For now this functionality is enough, for the next time, I would like to check if using the browser with the a go/ domain works, and does it pass requests to the webserver.

Thanks for reading and see you next time.

I have an old itch that always was in the back of my mind for years, where I wanted to understand how databases work under the hood.

Of course there are a lot of different types of databases, and each one contains a lot of different components. So it is a lot of ground to cover. Instead of just reading about them, I also want to implement bits and pieces.

So I decided that I should start working on some project that I can benefit from, and also implement some aspects of a database. I thought about starting with some simple implementation of a key-value store. The project that I think that will benefit of such a database is a clone of the go/links system.

Basically a go/links system, is a sort of bookmarking application for your browser, where when you input into the address bar some address that starts with go/ and a keyword, it will redirect the browser to some pre-stored site for that keyword. For example it is possible to define that go/facebook will take you to www.facebook.com, Or to any specific link that you desire.

Design

The basic components that I would need for the architecture of the system, are:

1. Webserver
2. Database

The Database will store the key-value items, where the key would be the link keyword, for example facebook. And the value would be the underlying link, www.facebook.com for example. I will write the database from scratch in Python, as this is really what I want to practice. I don’t look for great performance but mostly practicing concepts.

Basically it will hold an in memory dictionary, that will be flushed to disk and initialized from disk. I will use Protocol Buffers for the schema of the items that will be stored to disk. It allows serializing the data to a more compact representation, and also provide schema evolution if changes will occur in the future.

The Webserver will receive the requests of the go/ type, and redirect to the underlying value that is stored in the database. It will also allow creating and updating links. I will use FastAPI framework for the server.

In order to direct go/ requests to the webserver, I will update the /etc/hosts file.

Next Steps

In my next posts I will take the implementation step by step, and describe how I implement each part of the system, so you could try and replicate and even do better.

Thanks for reading, and see you soon.

Next post in the series.

In our Data Quality platform, we allow users to onboard different types of datasets. One of our initial goals on the platform was to provide the ability to write expectations for those datasets, which in turn help to determine the quality of the dataset.

The expectations are using the metrics that our platform produces for the datasets. Example metrics that the platform can produce for each dataset:

• Number of rows.
• Number of rows with null values in specific column.
• Average/Min/Max number of items in a column of type collection.

Each metric would return some number, in consequence our expectations should be able to do some arithmetic expression on those metrics.

A sample expression could look like: {null_email}/{count_rows}

The {null_email} placeholder expresses the amount of rows with a null value in the email column, and {count_rows} expresses the amount of rows in the dataset. Using the above expression, we get the proportion of rows that have null values in the email column. On the result of that expression the user can define a threshold which will describe the expectation.

For example: {null_email}/{count_rows} < 0.05

From the above expectation, the user expects that the dataset should contain less then 5% of rows with null value in the email column.

The users would provide these expectations through an API that the platform exposed. For an easier usage for the user, we allowed them to pass the expression as simple string, and the service would parse and evaluate it.

But which parser should I use for parsing and evaluating?

Parsers

For implementation simplicity I chose to use the jeasy/easy-rules repository with the MVEL expression language parser. And it worked pretty well. It allowed me to parse and evaluate the whole expectation out of the box. But naturally the requirements evolved and we wanted to introduce extra features in the expression itself, and wanted some more control over the expression language.

As a consequence of the changed requirements, I have started looking for other libraries that would provide me with more control over the parsing of the expressions. Our main language is Scala, so I looked for a Scala library that I could have used.

The first option that pops in, is using the scala-parser-combinators library, as once it was a built-in in the standard Scala library. But after investigating a bit more, it seemed that it was a pretty slow library, performance wise, so I kept looking, and found the FastParse parsing library by Li Haoyi. The first example of the library was an arithmetic parser, so it was somewhat a breeze to create the parser that I wanted. The main caveat was, that I didn’t want to evaluate the expression directly when parsed, but instead to create an AST, which I could evaluate later when providing the relevant metrics.

With a bit of manipulation I was able to create a parser that creates the AST, and the AST itself would be able to evaluate itself when needed.

The Solution

First of all I defined the Expressions that I would expect.

sealed trait Expression
case class Div(r: Expression, l: Expression) extends Expression
case class Mul(r: Expression, l: Expression) extends Expression
case class Add(r: Expression, l: Expression) extends Expression
case class Sub(r: Expression, l: Expression) extends Expression
case class Num(value: String) extends Expression
case class Metric(id: String) extends Expression

It contains the four basic arithmetic expressions, an expression that represents a number and an expression that represents a Metric.

After that I have defined the actual Fastparse patterns that would map onto those expressions.

def number[_: P]: P[Expression] = P(CharIn("0-9").rep(1)).!.map(Num)
def metric[_: P]: P[Expression] = P("{" ~ number.! ~ "}").map(Metric)
def factor[_: P]: P[Expression] = P(number | metric | parens)
def parens[_: P]: P[Expression] = P("(" ~/ addSub ~ ")")

def divMul[_: P]: P[Expression] = P(factor ~ (CharIn("*/").! ~/ factor).rep).map((astBuilder _).tupled)
def addSub[_: P]: P[Expression] = P(divMul ~ (CharIn("+\\-").! ~/ divMul).rep).map((astBuilder _).tupled)
def expr[_: P]: P[Expression] = P(addSub ~ End)

The patterns are basically the arithmetic example pattern from the fastparse documentation But instead of evaluating the result while parsing, it builds the AST. For the simple metric and number patterns, I map the parsed result directly on the relevant Expressions.

For the Arithmetic patterns (divMul and addSub) I modified a bit the example to create the relevant Expressions

def astBuilder(initial: Expression, rest: Seq[(String, Expression)]): Expression = {
    rest.foldLeft(initial) {
      case (left, (operator, right)) =>
        operator match {
          case "*" => Mul(left, right)
          case "/" => Div(left, right)
          case "+" => Add(left, right)
          case "-" => Sub(left, right)
        }
    }
  }

And if we run some tests, we can see the following results

"the parser" should "create an AST of only numeric expression" in {
    val expression = "3/2"
    val ast = Parser.parse(expression)
    ast shouldEqual Right(Div(Num("3"), Num("2")))
  }

  it should "create an AST of mixed operators" in {
    val expression = "3+4*5"
    Parser.parse(expression) shouldEqual Right(Add(Num("3"), Mul(Num("4"), Num("5"))))
  }

  it should "create an AST with a metric" in {
    val expression = "3+{4}/5"
    Parser.parse(expression) shouldEqual Right(Add(Num("3"), Div(Metric("4"), Num("5"))))
  }

The Parser object is just a wrapper for the fastparse parser, it just converts the parsing result into an Either.

object Parser {
  type Error = String
  def parse(expression: String): Either[Error, Expression] =
    fastparse.parse(expression, Patterns.expr(_))
      .fold((e, _, _) => Left(e), (s, _) => Right(s))
}

Next steps

From that simple example we were able to add more “Functions” to the expression that would be part of the syntax that we support in our Data Quality Expectations. And that allows us to customize the language of the expectations according to our user needs.

Thanks for reading !

In this post I will show, how we leveraged PureConfig, and were able to use its Sealed Families feature in order to have multiple configuration options for the same resource.

Or more specifically, how we allowed to pass in our configuration, different types of authentication configurations when creating an RDS connection configuration.

What is Pureconfig

PureConfig is Github’s library for basically converting configuration files into Scala Classes, more specifically and common, into case classes.

It is pretty simple to load a Typesafe supported configuration file into a case class using that library, as simple as the following configuration and code:

"db-conn": {
    "host": "localhost"
    "port": 5432
    "user": "admin"
    "password": "admin"
}

import pureconfig._
import pureconfig.generic.auto._

object Main extends App {
  case class DBConn(host: String, port: Int, user: String, password: String)
  case class ServiceConf(dbConn: DBConn)

  val conf = ConfigSource.default.load[ServiceConf]

  println(conf) // Right(ServiceConf(DBConn(localhost,5432,admin,admin)))
}

As we can see, it is pretty straightforward. We define a couple of case classes that describe the configuration file, and ask pureconfig to create an instance of that class filled with the correct values.

What is a Sealed Family

A Sealed Family allows us to create a sealed family of case classes which allows us to create different types of configuration options, depending on the type that we specify.

For example if we have different authentication options for our database connection, one option is to connect by user/password and the other one is to use user/IAM Token (for AWS RDS as an example), we can define them using a sealed trait, and some case classes.

We would see that exact example in the following sections.

Why do we use it

In our case as I have already mentioned, we rely on that feature for our connection to a Database. As we are using the AWS RDS service, we have also enabled there the IAM authentication method. Which means that the password for connecting to the Database is generated using an AWS RDSIamAuthTokenGenerator. For that generator some IAM related configurations are needed. An example of how to generate a real token you can find in my previous post.

But of course there are cases where we want to check our service locally, and so we would want to connect using a simple user/password option.

A sample configuration with IAM (./resources/db-iam.conf):

"db-conn": {
    "host": "localhost"
    "port": 5432
    "user": "admin"
    "auth": {
        "type": "iam"
        "iam": {
            "region": "us-west-2"
            "assumed-role": "arn:aws:iam::9999999999:role/some-role"
            "assume-role-session-name": "my-session"
        }
    }
}

A sample configuration with simple password (./resources/db-password.conf):

"db-conn": {
    "host": "localhost"
    "port": 5432
    "user": "admin"
    "auth": {
        "type": "password"
        "value": "admin"
    }
}

As we can see those configurations should create two different case classes. The type attribute, will tell PureConfig which case class to use. The next section will contain a working example with some explanations.

Implementation

The first basic configuration is needed for the IAM configuration that was mentioned in the previous section:

case class IamConf(region: String, assumedRole: String, assumeRoleSessionName: String)

We would like to allow the previously mentioned DBConn case class to handle two types of authentications. The IAM one, and a simple password one.

For that we will create a sealed trait that will combine both of the options:

sealed trait DBAuth
case class password(value: String) extends DBAuth
case class iam(iam: IamConf) extends DBAuth

We will call that trait DBAuth and extend the options (case classes) with that trait.

The simple password option, will just contain the password itself.

The iam option, will contain all the relevant fields that were mentioned in the IamConf case class.

And now the DBConn case class would look like this:

case class DBConn(host: String, port: Int, user: String, auth: DBAuth)

We can notice that there is an auth field, that is of type of the DBAuth trait. And it will accept correctly the type of the auth that is specified in the configuration file.

The ServiceConf case class stays the same:

case class ServiceConf(dbConn: DBConn)

So now, if we load the configuration files for each of the types we would get the following results:

ConfigSource.file("./resources/db-password.conf").load[ServiceConf]
// Right(ServiceConf(DBConn(localhost,5432,admin,password(admin))))

ConfigSource.file("./resources/db-iam.conf").load[ServiceConf]
// Right(ServiceConf(DBConn(localhost,5432,admin,iam(IamConf(us-west-2,arn:aws:iam::9999999999:role/some-role,my-session)))))

All is good, but there is a little problem. If we want to access the auth fields, we are unable to do it easily as the DBAuth trait doesn’t contain any common fields with the extending case classes.

Which means, that this code won’t work:

configPass.map(_.dbConn.auth.password)

Because DBAuth doesn’t have a password attribute.

Common attribute

Basically what we tried to achieve with the DBAuth configuration. Is to have a single place for having the password that is needed for the connection. It can come from different configuration types, but eventually it should return for us a password.

So basically we have a common attribute for both implementations, and it is the password attribute.

For the simple password configuration type, we will just return the password that is written in the configuration.

But, for the iam configuration type, we would want to use the IAM attributes to generate a token that we would use as the password.

Because we would need to generate the token whenever we call the password attribute, we would want to make that attribute a function. So we would add a method that is called password to the DBAuth trait, and implement it in each of the subtypes:

sealed trait DBAuth {
    def password: String
}

case class password(value: String) extends DBAuth {
    override def password: String = value
}
case class iam(iam: IamConf) extends DBAuth {
    override def password: String = TokenGenerator(iam).getToken
}

// Just a dummy class for the token generation feature.
case class TokenGenerator(iam: IamConf) {
    def getToken: String = "some token"
}

Now it is possible to call the following code, in order to get the appropriate password:

configPass.map(_.dbConn.auth.password)
// Right(admin)

configIam.map(_.dbConn.auth.password)
// Right(some token)

More Beautification

Currently if we would like to access the user and password attributes, it would look a bit finicky, at least to me. Let’s look at the following example:

val confPass = configPass.getOrElse(throw new RuntimeException) // Extract the configuration object or throw an exception.
confPass.dbConn.user
confPass.dbConn.auth.password

We can see that the path to the user and to the password, is a bit different. I would prefer to have the password on the same level as the user. The solution is pretty easy, we can add a method to the DBConn that would shorten the path for us. Like this:

case class DBConn(host: String, port: Int, user: String, auth: DBAuth) {
    def password: String = auth.password
}

And now it is possible to call the password attribute on the same level as the user attribute.

val confPass = configPass.getOrElse(throw new RuntimeException) // Extract the configuration object or throw an exception.
confPass.dbConn.user
confPass.dbConn.password

And it will call the appropriate password method of the appropriate DBAuth implementation.

Hope this post was helpful, thank you for reading.

As I tried to describe in the title, apparently using a ConnectionPool on Postgres RDS with the IAM authentication is not that straightforward.

One of the caveats of the IAM authentication, is that the token that is generated is available for 15 minutes. Which means that after 15 minutes a new connection needs to regenerate a token. But the connection pool that we chose doesn’t have a built-in option to pass some token generator, or some similar capabilities.

For that we have created a simple DataSource that would generate a new token when a getConnection method is called.

The whole solution is described in the following sections.

How to authenticate with an IAM

In order to do an IAM Authentication with RDS, we are using the AWS Java SDK. And more specifically the following services:

1. AWSSecurityTokenServiceClientBuilder - In order to fetch the credentials.
2. RdsIamAuthTokenGenerator - To generate the RDS token using the credentials.

Both services are pretty straight forward, but in any case, this is how we fetch the credentials:

val stsClient = AWSSecurityTokenServiceClientBuilder.standard
      .withRegion(regionName)
      .build

val roleRequest = new AssumeRoleRequest()
      .withRoleArn(assumedRole)
      .withRoleSessionName(assumeRoleSessionName)

val roleResponse = stsClient.assumeRole(roleRequest)
val sessionCredentials = roleResponse.getCredentials

new BasicSessionCredentials(
      sessionCredentials.getAccessKeyId,
      sessionCredentials.getSecretAccessKey,
      sessionCredentials.getSessionToken
)

After we have the basic credentials, we can start creating the RDS token:

val generator = RdsIamAuthTokenGenerator.builder
      .credentials(new AWSStaticCredentialsProvider(credentials))
      .region(region)
      .build

generator.getAuthToken(
      GetIamAuthTokenRequest.builder
        .hostname(rdsConf.host)
        .port(rdsConf.port)
        .userName(rdsConf.userName)
        .build
)

The rdsConf is just a configuration object that we use to hold the relevant configuration for RDS.

Now that we have the authentication token, we can now use it as the password for connecting to our RDS instance.

But bear in mind that this token is only valid for 15 minutes. A small note here, if a connection was established using that token, then while the connection is still open, it will work for more than 15 minutes. But once the connection is broken the same token can’t be used to reconnect if the 15 minutes expiry time has passed.

How to define the connection pool

We went with using HikariCP as our connection pooling solution. It was pretty straight forward to initialize it and start using it. With a few lines of code we were able to replace our previous non CP solution. Here is how we initialize it:

val hikariConf = new HikariConfig()
hikariConf.setJdbcUrl(rdsConf.url)
hikariConf.setDataSource(new PGCustomDataSource(rdsConf, buildConnectionProperties))

val hikariDataSource = new HikariDataSource(hikariConf)

DSL.using(hikariDataSource, SQLDialect.valueOf(rdsConf.driver.dbType))

The PGCustomDataSource is our implementation of the datasource, where we refresh the RDS IAM token. We will see the solution in the next step.

The buildConnectionProperties is just some more properties that we use to enable SSL connection to the RDS.

Basically after creating the HikariDataSource we pass it to our database abstraction framework, which in our case is jOOQ.

Updating the password when a connection is requested

The most naive approach for updating the password, is just to override the getConnection method of the data source. In our case we are connecting to a postgres DB, so we were using the PGSimpleDataSource and overriding its getConnection method. Well actually we were overriding the one in BaseDataSource which the PGSimpleDataSource extends. The code is pretty simple:

class PGCustomDataSource(rdsConf: RdsConf, connectionProperties: Properties) extends PGSimpleDataSource {
  override def getConnection: Connection = {
    connectionProperties.setProperty("user", rdsConf.userName)
    connectionProperties.setProperty("password", rdsConf.password)
    DriverManager.getConnection(rdsConf.url, connectionProperties)
  }
}

The getConnection method fetches the user and password from the configuration and passes it to the DriverManager. Similar to what is going on in the getConnection of BaseDataSource.

One note though, the rdsConf.password is actually a method, that generates the token. We did a neat trick with that configuration where it can generate a password or fetch one from the configuration object directly, using some pureconfig magic.

And that is it, now our connection pool can refresh the RDS IAM tokens and allow our service to continue working.

Thanks for reading !

I recently have started following a recipes channel on YouTube. The thing that is missing for me, is that I can’t search for recipes with specific ingredients. Luckily the videos description contains the ingredients. So I was thinking about downloading the descriptions of all the videos. And then cataloging them somewhere for easier search.

In this post, I will show you how I have downloaded all the descriptions of all the videos in the channel using Google’s Youtube API, Python and the requests package.

API

First of all to use Youtube’s API, we need to onboard it in Google Cloud Console. Under APIs & Services choose Library, search for YouTube Data API, in my case it was version 3 (v3), choose it and enable it.

After that we need to create an API Key (for the naive solution). We can find it under the credentials tab.

When we have the key in hand, we can move to the next section and start calling the API. In my case I have used Python for that with the requests package.

Fetching metadata

As I have already mentioned, the whole idea of that mini project was to fetch the descriptions of the videos from a specific channel. There were two endpoints that I had to use in order to fetch the descriptions.

The first one, was to fetch all the video IDs of that channel, and then for each video to fetch the description.

The first endpoint that I have used, was the search. Using this one, I was able to fetch all the video IDs. I have used the following URL:

url = f'https://youtube.googleapis.com/youtube/v3/search?part=snippet&maxResults=50&type=video&channelId={channel_id}&key={self.api_key}'

The parameters that I have used in the request were:

1. part=snippet - Specifies that I want to have a snippet of the data of the results. It is what the documentation asks to use.
2. maxResults=50 - The number of results to return. 50 is the max.
3. type=video - What type of results are we interested in. In my case it was only videos. Otherwise it might return playlists.
4. channelId={channel_id} - The results for a specific channel.
5. key={api_key} - The API key that we have created earlier.

In my case the the amount of videos in the channel was greater than 50, so I had to use nextPageToken which contains the ID for the next page of the results. So my subsequent search requests used pageToken={next_page}.

The result of the search request also contained a description for each video that it returned, but it was an abbreviated one, so I had to use another endpoint to fetch the whole description of each video.

For each result, I have created a list of video IDs using the following list comprehension:

video_ids = [
            search_result['id']['videoId']
            for search_result in response['items']
            if 'videoId' in search_result['id']
        ]

And using the videos endpoint, I would pass the list of IDs to get the result with the full description.

url = f'https://youtube.googleapis.com/youtube/v3/videos?part=snippet&id={",".join(video_ids)}&key={self.api_key}'

The parameters in this case were:

1. part=snippet - As in the search request.
2. id={",".join(video_ids)} - A comma separated video IDs list.
3. key={api_key} - The API key that we have created earlier, the same one we used in the search request. The result of this request contained a result for each video that was passed with its full description.

And that is basically what I did to fetch the descriptions of all the videos of a channel.

Thanks for reading !