9. February 2023

How to call Rust functions from Python, Ruby and Zig

Rust language is great for creating libraries and drivers which can be consumed by other languages like Python, Ruby or Zig.

Let’s consider following Rust application Cargo.toml:

[package]
name = "rustlib"
version = "0.1.0"
edition = "2021"

[lib]
name = "rust_lib"
crate-type = ["dylib"]

File src/lib.rs:

#[no_mangle]
pub extern "C" fn add(left: usize, right: usize) -> usize {
    left + right
}

The next step is to build the library:

cargo build --release

The output library is stored in ./target/release/librust_lib.so

Python

Invoking the add function from Python is very easy:

import ctypes
lib = ctypes.CDLL("./target/release/librust_lib.so")
lib.add(1,2)

Ruby

In case of Ruby we will need ffi gem.
Installation on OpenSuse:

sudo zypper install ruby3.1-rubygem-ffi

Ruby code:

require 'ffi'

module MyLib
  extend FFI::Library
  ffi_lib './target/release/librust_lib.so'
  attach_function :add, [ :int, :int ], :int
end

puts MyLib.add 1, 2

Zig

Zig will require little bit more stuff. We need to generate C headers from Rust, which then can be loaded to Zig. Install cbindgen for the conversion:

cargo install cbindgen

Generate header file from the library.

cbindgen --lang c --output rustlib.h

Create Zig application in zig2rust:

const std = @import("std");
const rustlib = @cImport(@cInclude("rustlib.h"));

pub fn main() !void {
    const stdout = std.io.getStdOut().writer();
    const result = rustlib.add(1,2);
    try stdout.print("Result is {d}.\n", .{result});
}

Compile Zig application:

zig build-exe zig2rust.zig -I. -l target/release/librust_lib.so

Run the application:

./zig2rust

21. December 2022

Rust Bare Metal application for ESP32, desktop, Android and iOS

Rust language and tooling are very powerful. It makes it easy to build for different platforms and architectures and still have performance close to C language.

It’s possible to write the same application for ESP32 with Xtensa architecture or ESP32-C3 RISC-V architecture. The portability of Rust code is high. Changing the target and adding a few wrapper functions makes it possible to build the same application for the desktop or web browser with WebAssembly. Once the WebAssembly is ready, it’s possible to turn the application into Progressive Web App (PWA) which can be installed on Android or iOS.

ESP32 Spooky Maze game is example of application which can work on ESP32 and also on mobile device. The shared core code contains the main part of the implementation, and each platform has its tiny wrapper.

The example Rust application uses Embedded Graphics to draw images. When the app is running on real HW, it’s transferred to the display via SPI using ESP-HAL. The desktop version is using SDL2 to interact with Linux, macOS, or Windows. The web version is using WASM, and framebuffer is serialized to HTML5 canvas. PWA application for Android also supports access to Accelerometer, so it can simulate similar behavior like IMU on ESP32-C3-DevKit-RUST or ESP32-S3-BOX where user can tilt the device to move the character in the maze.

Web version of the application with PWA support: Spooky (full-screen mode)

Embedded version of the application: ESP32-S3-BOX, M5CORE-FIRE (M5Stack) and many more.

Thanks to cloud development IDEs, it’s possible to build the application on GitPod.io or GitHub Codespaces and run it even without real HW using Wokwi simulator.

31. October 2022

openSUSE Rust Bevy application failed with “Unable to find a GPU”

Bevy is data-driven engine written in Rust. The repository of Bevy contains several examples which can be started by a command like:

git clone --depth 1 https://github.com/bevyengine/bevy.git
cd bevy
cargo run --example alien_cake_addict

Users of openSUSe might experience following error:

hread 'main' panicked at 'Unable to find a GPU! Make sure you have installed required drivers! For extra information, see: https://github.com/bevyengine/bevy/blob/latest/docs/linux_dependencies.md', crates/bevy_render/src/renderer/mod.rs:121:10
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

The problem is caused by missing Vulkan libraries in the system. This can be confirmed by running vkcube which may result in the following error:

vkEnumerateInstanceExtensionProperties failed to find the VK_KHR_surface extension.

Do you have a compatible Vulkan installable client driver (ICD) installed?
Please look at the Getting Started guide for additional information.

Check which graphic card is installed in the system:

sudo lspci -nnk | grep -A3 VGA

Which might result in a message like this:

00:02.0 VGA compatible controller [0300]: Intel Corporation CometLake-U GT2

With this knowledge, it’s clear that library Vulkan Intel is missing and can be installed simply by:

sudo zupper install libvulkan_intel

Application vkcube should work after this change.

30. August 2022

Unable to flash ESP32 (S2, S3, C3) with these USB-C cables

USB-C is becoming more and more popular. A straightforward assumption is that you can replace the old cable with a USB-A connector with USB-C, and everything should be the same. This assumption is wrong.

Some cables do not work well with ESP32, S2, S3, and C3. Here you can find information about cables which does not work and it’s not possible to flash dev boards with the chip with espflash, idf.py or esptool.py.

A typical error message looks like this:

Serial port: /dev/tty.usbserial-110
Connecting...

Unable to connect, retrying with extra delay...
Unable to connect, retrying with default delay...
Unable to connect, retrying with extra delay...
Error: espflash::connection_failed

  × Error while connecting to device
  ╰─▶ Failed to connect to the device
  help: Ensure that the device is connected and the reset and boot pins are not being held down

USB-C to micro-USB connected to boards ESP32-S2-USB-OTG and ESP32-S3-USB-OTG, length 60 cm, marks on cable “AWM 80 C 30V VW-1 USB 2.0 CABLE”:

  • directly connected to mac M1 2020 – does not work
  • workaround #1: press and hold boot button on the board, start flash command, release boot button after flashing process starts
  • workaround #2: connect mac M1 to monitor/hub with USB-C and connect the cable there
  • workaround #3: use computer with Windows or Linux, the cable seems to work correctly with these OSes

1. April 2022

How to develop for ESP32-C3 with Rust on macOS with Lima using Dev Container in VS Code

Lima is a solution for macOS for managing Linux VM on macOS which plays well with Dev Containers. It has several advantages over Docker Desktop for macOS or Podman.

Let’s see how it can be used for the development of software for embedded hardware like ESP32-C3 using source code from Ferrous Systems training:

git clone https://github.com/ferrous-systems/espressif-trainings.git

Install Lima and Docker-CLI:

brew install lima docker

Create Linux VM with Dockerd (following instructions from Kevin O’Brien – Utilizing Docker CLI without Docker Desktop):

curl https://raw.githubusercontent.com/lima-vm/lima/master/examples/docker.yaml -O
limactl start ./docker.yaml
limactl shell docker
sudo systemctl enable ssh.service

There is one important tweak in the Lima configuration. It’s necessary to enable write operation otherwise, the workspace mounted from VS Code is read-only. Open file ~/.lima/docker/lima.yaml and add writable flag to desired folder:

mounts:
- location: "~"
  writable: true

Restart Lima to apply changes.

limactl stop docker
limactl start docker

Create context for Docker-CLI to connect to dockerd running in the VM:

docker context create lima --docker "host=unix://${HOME}/.lima/docker/sock/docker.sock"
docker context use lima

Open VS Code with the installed Remote Container plugin and click Re-Open in Container:

cd espressif-trainings
code .

Open terminal in VS Code and build the example:

cd intro/hardware-check
cp cfg.toml.example cfg.toml
cargo build

Flashing of the resulting file could be done by espflash and mounting the device to Lima or using a tool like Adafruit WebSerial ESPTool. The file for flashing is located in the directory target/release.