The main microcontroller in the Orb is responsible for a wide range of critical tasks to ensure the device's functionality and reliability. Its duties encompass powering on the Orb by initiating a specific sequence for the Jetson and activating multiple power lines with various voltages, while simultaneously monitoring these voltages at a high frequency to detect any failures. It also oversees the Orb's internal temperatures, voltage levels, and logs any errors or warnings that occur during operation. The microcontroller and the Jetson communicate over the CAN bus Optically, the Orb is an intricate device, and the microcontroller coordinates IR LED and camera synchronization, ensures safety, controls the liquid lens, and adjusts the mirror for optimal operation. For user interaction, it handles button inputs for power and starting signups and controls RGB LEDs for visual feedback. The mcuboot bootloader manages the Zephyr application in two slots, allowing for over-the-air updates with rollback capabilities.
The Orb comes in two different hardware versions. Support for both is provided in this repository:
- Pearl: Current hardware iteration of the Orb, which you can find around the world.
- Diamond: Next hardware iteration of the Orb that will be released in the future. It is currently in development and might be subject to breaking changes.
You can set up your development environment directly on your machine (preferred for Windows users), or you may use the provided Docker image. A step-by-step guide is available below. Note that all of these steps assume that you have an SSH key set up properly with GitHub and that you have access to all the microcontrollers repos. These repositories are enumerated in the west.yml file.
-
Install the
west
meta-tool.pip3 install west
-
Create an empty directory where the projects and dependencies will be located.
export REPO_DIR=$HOME/firmware # or any other directory mkdir "$REPO_DIR"
-
Clone the manifest repository using west.
cd "$REPO_DIR" west init -m <repo-url.git> --mr main
This will create a directory called
orb
. -
Now import all projects and dependencies.
west update
- If you prefer to use Docker, you can use the provided Dockerfile.
cd "$REPO_DIR"/orb/public/utils/docker make build make shell
These instructions are mainly just an adaptation of the instructions in the Zephyr getting started guide.
-
Install the dependencies. Two ways:
- Follow instructions in this section
for installing dependencies.
- Then:
pip3 install -r "$REPO_DIR"/zephyr/scripts/requirements.txt
- Then:
- Or install the Conda environment provided here.
conda env create -f orb/public/utils/env/environment.yml conda activate worldcoin
- Follow instructions in this section
for installing dependencies.
-
Install a toolchain.
You may change
INSTALL_LOC
to choose an installation location. You may also changeSDK_VER
to choose a specific toolchain version:export SDK_VER=0.16.5
This script will install the Zephyr SDK in your home directory:
tmp=$(mktemp) cat > "$tmp" <<EOF #!/bin/bash set -ue set -o pipefail install_zephyr_sdk() { INSTALL_LOC=\$HOME KERNEL=\$(uname -s | tr '[[:upper:]]' '[[:lower:]]') [ "\$KERNEL" = darwin ] && KERNEL=macos ARCH=\$(uname -m) [ "\$ARCH" = arm64 ] && ARCH=aarch64 if [ -z "\${SDK_VER-}" ]; then if ! SDK_VER=\$(curl -s https://api.github.com/repos/zephyrproject-rtos/sdk-ng/releases/latest \\ | grep tag_name \\ | awk '{print substr(\$2, 3, length(\$2)-4)}'); then echo "Some error occurred when trying to determine the latest SDK version" >&2 return 1 fi fi echo "SDK_VER is '\$SDK_VER'" TAR_NAME=zephyr-sdk-\${SDK_VER}_\${KERNEL}-\${ARCH}_minimal.tar.xz echo "TAR_NAME is \$TAR_NAME" URL=https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v\${SDK_VER}/\${TAR_NAME} if [ ! -e "\$INSTALL_LOC/zephyr-sdk-\${SDK_VER}/.__finished" ]; then echo "Downloading \${TAR_NAME}..." && ( cd "\$INSTALL_LOC" && curl -JLO "\$URL" ) && echo 'Decompressing...' && (cd "\$INSTALL_LOC" && tar xf "\$TAR_NAME" ) && ( cd "\$INSTALL_LOC"/zephyr-sdk-\${SDK_VER} && ./setup.sh -t arm-zephyr-eabi -h -c ) && rm "\$INSTALL_LOC/\$TAR_NAME" && echo > "\$INSTALL_LOC"/zephyr-sdk-\${SDK_VER}/.__finished else echo "SDK already exists. Skipping." fi } install_zephyr_sdk EOF chmod +x "$tmp" "$tmp"
-
(Linux-based OS) Install udev rules to allow for flashing as a non-root user
# make sure to set $SDK_VER, based on previous step sudo cp zephyr-sdk-${SDK_VER}/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d sudo udevadm control --reload
-
Install the protobuf compiler.
if [ "$(uname -s)" = Darwin ]; then brew install protobuf-c else sudo apt install protobuf-compiler fi pip3 install protobuf grpcio-tools
-
Install CMSIS Pack for PyOCD
pyocd pack install stm32g474vetx
-
Export CMake packages.
cd "$REPO_DIR"
west zephyr-export
Your directory structure now looks similar to this:
firmware
├── bootloader (mcuboot)
├── modules (dependencies)
├── orb (this repository)
└── zephyr (os)
See the board-specific documentation for the main board.
Use openOCD with Zephyr patches to get the most out of your debugging experience, either from the Zephyr SDK (in Host Tools) or compiled manually using this script.
To fully use the thread-aware debugging, make sure to use:
CONFIG_DEBUG_THREAD_INFO=y
Print out the bootloader and main MCU application logs using:
# replace /dev/ttyxxx with your UART device
python "$REPO_DIR"/orb/public/utils/debug/uart_dump.py -p /dev/ttyxxx -b 115200
There are 2 microcontrollers in the Orb, the main and the security microcontrollers. This repository initially contains source code for both but, because the security features of the Orb are not open-sourced at the moment, the security microcontroller source code has been removed.
For people with access to the private repositories, West tracks the repositories to pull in your workspace and all you
need to do is to enable the internal
group in the West configuration:
west config --local manifest.group-filter "+internal"
west update
Unless otherwise specified, all code in this repository is dual-licensed under either:
- MIT License (LICENSE-MIT)
- Apache License, Version 2.0, with LLVM Exceptions (LICENSE-APACHE)
at your option. This means you may select the license you prefer to use.
Any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.