Convert Figma logo to code with AI

rsta2 logocircle

A C++ bare metal environment for Raspberry Pi with USB (32 and 64 bit)

2,244
293
2,244
12
View on GitHub

Top Related Projects

raspberrypi's avatar

pico-sdk

4,717

nRF24's avatar

RF24

2,441

OSI Layer 2 driver for nRF24L01 on Arduino & Raspberry Pi/Linux Devices

espressif's avatar

arduino-esp32

16,349

Arduino core for the ESP32

arduino's avatar

ArduinoCore-avr

1,460

The Official Arduino AVR core

Quick Overview

Circle is a C++ bare metal programming environment for the Raspberry Pi. It provides a foundation for developing operating systems, firmware, and low-level applications directly on Raspberry Pi hardware without relying on an existing operating system.

Pros

  • Offers direct hardware access and control for Raspberry Pi devices
  • Supports multiple Raspberry Pi models, including Pi 1-4, Zero, and Compute Modules
  • Provides a comprehensive set of libraries for various hardware components and protocols
  • Includes sample programs and tutorials for learning bare metal programming

Cons

  • Requires advanced programming skills and understanding of hardware architecture
  • Limited compared to full-fledged operating systems in terms of features and abstractions
  • May have a steeper learning curve for developers accustomed to higher-level programming environments
  • Documentation could be more extensive for some advanced topics

Code Examples

  1. Blinking an LED:
#include <circle/actled.h>
#include <circle/timer.h>

CActLED led;

void Kernel::Run(void)
{
    while (1)
    {
        led.On();
        CTimer::SimpleMsDelay(500);
        led.Off();
        CTimer::SimpleMsDelay(500);
    }
}
  1. Reading GPIO input:
#include <circle/gpiopin.h>

CGPIOPin button(17, GPIOModeInput);

void Kernel::Run(void)
{
    while (1)
    {
        if (button.Read() == LOW)
        {
            // Button pressed
        }
    }
}
  1. Using UART for serial communication:
#include <circle/serial.h>

CSerialDevice serial;

void Kernel::Run(void)
{
    serial.Write("Hello, World!\n", 14);
    
    char buffer[100];
    int bytesRead = serial.Read(buffer, sizeof(buffer));
    // Process received data
}

Getting Started

  1. Clone the Circle repository:

    git clone https://github.com/rsta2/circle.git

  2. Install the required toolchain (ARM cross-compiler) for your system.

  3. Build the Circle libraries:

    cd circle
./configure
make

  4. Create a new project in the sample directory or modify an existing sample.

  5. Build your project:

    cd sample/yourproject
make

  6. Copy the generated kernel.img to your Raspberry Pi's SD card and boot.

Competitor Comparisons

raspberrypi logo

pico-sdk

4,717

Pros of pico-sdk

  • Officially supported by Raspberry Pi, ensuring compatibility and regular updates
  • Extensive documentation and examples for easier development
  • Broader community support and ecosystem

Cons of pico-sdk

  • Limited to Raspberry Pi Pico and RP2040-based boards
  • Steeper learning curve for beginners compared to Circle's simplicity

Code Comparison

pico-sdk:

#include "pico/stdlib.h"

int main() {
    gpio_init(PICO_DEFAULT_LED_PIN);
    gpio_set_dir(PICO_DEFAULT_LED_PIN, GPIO_OUT);
    while (true) {
        gpio_put(PICO_DEFAULT_LED_PIN, 1);
        sleep_ms(500);
        gpio_put(PICO_DEFAULT_LED_PIN, 0);
        sleep_ms(500);
    }
}

Circle:

#include <circle/actled.h>
#include <circle/scheduler.h>

class CKernel : public CApplication {
public:
    virtual void Run(void) {
        while (1) {
            m_ActLED.On();
            CScheduler::Get()->MsSleep(500);
            m_ActLED.Off();
            CScheduler::Get()->MsSleep(500);
        }
    }
};

Both examples demonstrate LED blinking, showcasing the different approaches and syntax used by each framework.

nRF24 logo

RF24

2,441

OSI Layer 2 driver for nRF24L01 on Arduino & Raspberry Pi/Linux Devices

Pros of RF24

  • Focused library for nRF24L01 and nRF24L01+ 2.4GHz wireless modules
  • Extensive documentation and examples for various platforms
  • Active community and regular updates

Cons of RF24

  • Limited to specific wireless modules, not a general-purpose OS
  • Requires additional hardware components for full functionality
  • May have steeper learning curve for beginners in embedded systems

Code Comparison

RF24:

RF24 radio(7, 8);  // CE, CSN pins
radio.begin();
radio.openWritingPipe(address);
radio.write(&data, sizeof(data));

Circle:

#include <circle/startup.h>
CKernel Kernel;
CScreenDevice Screen;
Kernel.Initialize();
Screen.Write("Hello World", 11);

Key Differences

  • RF24 is a specialized library for wireless communication, while Circle is a bare metal programming environment for Raspberry Pi
  • Circle provides a broader set of features for OS-like functionality, whereas RF24 focuses on a specific wireless protocol
  • RF24 is cross-platform and can be used with various microcontrollers, while Circle is specific to Raspberry Pi hardware
espressif logo

arduino-esp32

16,349

Arduino core for the ESP32

Pros of arduino-esp32

  • Broader hardware support: Designed specifically for ESP32 microcontrollers
  • Extensive library ecosystem: Leverages Arduino's vast collection of libraries
  • Easier integration with existing Arduino projects

Cons of arduino-esp32

  • Less low-level control: Abstracts some hardware-specific features
  • Potentially higher resource usage due to Arduino framework overhead
  • Limited to ESP32 family, while Circle supports multiple Raspberry Pi models

Code Comparison

arduino-esp32:

#include <WiFi.h>

void setup() {
  WiFi.begin("SSID", "PASSWORD");
  while (WiFi.status() != WL_CONNECTED) {
    delay(1000);
  }
}

Circle:

#include <circle/net/netsubsystem.h>

CNetSubSystem NetSubSystem;

void Initialize() {
  NetSubSystem.Initialize();
  NetSubSystem.GetConfig()->SetDHCP(TRUE);
}

The arduino-esp32 code demonstrates easier Wi-Fi setup, while Circle shows more low-level network initialization. arduino-esp32 benefits from simpler syntax and built-in Wi-Fi support, whereas Circle offers more granular control over system components.

arduino logo

ArduinoCore-avr

1,460

The Official Arduino AVR core

Pros of ArduinoCore-avr

  • Extensive library support and ecosystem for Arduino boards
  • Well-documented and beginner-friendly API
  • Large community and widespread adoption

Cons of ArduinoCore-avr

  • Limited to AVR microcontrollers, less flexible for other platforms
  • Higher-level abstraction may result in less efficient code
  • Slower development cycle for core updates

Code Comparison

ArduinoCore-avr:

void setup() {
  pinMode(LED_BUILTIN, OUTPUT);
}

void loop() {
  digitalWrite(LED_BUILTIN, HIGH);
  delay(1000);
  digitalWrite(LED_BUILTIN, LOW);
  delay(1000);
}

Circle:

#include <circle/actled.h>
#include <circle/scheduler.h>

void CActLED::On(void)
{
    m_nEnableCount++;
    Write(TRUE);
}

Summary

ArduinoCore-avr is ideal for beginners and rapid prototyping on AVR-based Arduino boards, offering a vast ecosystem and easy-to-use API. Circle, on the other hand, provides a bare-metal environment for Raspberry Pi, allowing for more low-level control and potentially better performance. The choice between the two depends on the target platform and the developer's needs for abstraction versus control.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Circle

Overview

Circle is a C++ bare metal programming environment for the Raspberry Pi. It should be usable on most existing models (see "Support Status" below). Circle provides several ready-tested C++ classes and add-on libraries, which can be used to control different hardware features of the Raspberry Pi. Together with Circle there are delivered several sample programs, which demonstrate the use of its classes. Circle can be used to create 32-bit or 64-bit bare metal applications.

Circle includes bigger (optional) third-party C-libraries for specific purposes in addon/ now. This is the reason why GitHub rates the project as a C-language-project. The main Circle libraries are written in C++ using classes instead. That's why it is called a C++ programming environment.

The 51st Step

This release offers a significantly improved implementation of the TCP/IP network stack. It supports TCP congestion control according to RFC 5681 with Fast Retransmit and Fast Recovery. Also the unnecessary copying of frames and data in the stack is largely prevented. This improves throughput very much, especially when a Raspberry Pi with 100 MBps Ethernet is connected to a Gigabit network.

The socket API is nearly unchanged, but the new MSG_MORE flag can be specified, when calling CSocket::Send() on TCP sockets, which prevents the immediate delivery of received data on the receiver side, when more data follows. CSocket::Bind() can be called with port 0 to bind to an ephemeral port, which can be requested using CSocket::GetOwnPort(). CSocket::SendTo() without preceding Bind() or Connect() is allowed too, which automatically assigns an ephemeral port.

Circle supports the extended C++ standard library support (LLVM libc++ port) in the circle-stdlib project in several ways (e.g. with the new STDLIB_SUPPORT=4 level).

The recommended toolchain to build Circle applications is now based on GCC 15.2.Rel1. See the link in the Build section! Circle is built with -std=c++17 by default now. There are options for selecting C++14 (previous default) and C++20 for the configure tool, beside the new --kernel-max-size, --clang and --kasan options. Enter ./configure --help for more info!

The recommended firmware has been updated in boot/.

More new features:

  • A CDevice instance can have property strings for vendor, product, serial number and function (e.g. the USB interface) now. These strings are assigned for all USB- and for NVMe devices, and can be used to distinguish devices of the same class. CDeviceNameService::ListDevices() can show these properties.
  • The system option USE_GPIO_MANAGER_FIQ has been added. When an application needs multiple FIQ-triggered GPIO interrupt pins, the class CGPIOPinFIQ cannot be used. It is also not possible to use CGPIOPinFIQ together with the class CGPIOManager to handle more GPIO pins with IRQ. Now one can define this option to enable CGPIOManager and all GPIO pins, which use an interrupt, to use the FIQ to reduce GPIO interrupt latency. The GPIO interrupt handler will run at FIQ_LEVEL then.
  • CGPIOClock::StartRate() can use fractional dividers on Raspberry 1-4. Before only integer dividers were supported. Now automatically a fractional divider will be used with MASH 1, if necessary.
  • The class CPipe (an unidirectional inter-process communication channel using a FIFO) and the methods CMutex::TryAcquire() and CSemaphore::DownWithTimeout() have been added to the scheduler library. CSemaphore objects can have the initial count of zero now. test/pipe demonstrates CPipe.
  • Sound devices allow writing and reading samples in the SoundFormatFloat32 now. Samples must be of the data type float in the range [-1.0 .. 1.0] in this case. sample/34-sounddevices and test/sound-controller can be configured to use this.
  • The class CPWMSoundBaseDevice supports the M/S PWM mode, which is also the default now. This should lead to a better audio quality and suppresses hum, when the PWM signal is delivered via the GPIO header.
  • The class CEMMCDevice in addon/SDCard supports external SDIO breakout boards at GPIO22-27 now as device "emmc2" and "SD2:" in FatFs. This does work with the EMMC host only (not with USE_SDHOST). On the Raspberry Pi 4 and CM4 the class can be instantiated twice with different device selector parameter specified to the constructor.
  • A CSSD1309Display graphics-mode driver for the SSD1309 128x64 OLED display controller (I2C and SPI) has been added to addon/display.
  • A CMCP23017 driver for the MCP23017 16-bit I2C GPIO expander has been added to the addon/gpio.
  • The MPU-6050 driver in addon/sensor has been extended and returns a scaled acceleration and gyroscope output now. The acceleration and gyroscope range and digital low-pass filter bandwidth can be configured. The sample adds a graphics mode.
  • The serial bootloader images are much smaller now and are able to load kernel images of up to about 8 MB.

A number of fixes have been applied:

  • CGPIOClock::Stop() was operating on the wrong clock. This caused a stop of the UART clock, when GPIOClock2 was started.
  • CMachineInfo::GetClockRate() now favors the firmware function GET_CLOCK_RATE_MEASURED over GET_CLOCK_RATE, which reported a wrong Core clock rate, when CCPUThrottle was used. The reported value is rounded to the closest MHz value.
  • The cmdline.txt option wm8960tune= has been added as a workaround. Add the given value to the fractional (K) part of PLL1 input/output frequency ratio (treated as 24-digit binary number) of the WM8960 Codec to suppress clicks/pops (range -10000 to 10000, default 0).
  • There have been multiple issues with the handling of TCP FIN packets, which were leading to a delayed termination of connections.
  • There was a problem found in the scheduler using KASan, which was accessing a task object after deleting it.

Features

Only the features with a "x" or other info are currently supported on the Raspberry Pi 5.

Circle supports the following features:

GroupFeaturesRaspberry Pi 5
C++ build environmentAArch32 and AArch64 supportAArch64 only
Basic library functions (e.g. new and delete)x
Enables all CPU caches using the MMUx
Interrupt support (IRQ and FIQ)IRQ only
Multi-core support (Raspberry Pi 2, 3 and 4)x
Cooperative non-preemptive schedulerx
CPU clock rate managementx
Clang/LLVM support (experimental)x
Debug supportKernel logging to screen, UART and/or syslog serverx
C-assertions with stack tracex
Hardware exception handler with stack tracex
GDB support using rpi_stub (Raspberry Pi 2 and 3)
Serial bootloader (by David Welch) includedx
Software profiling support (single-core)x
QEMU support
Kernel Address Sanitizer supportx
SoC devicesGPIO pins (with interrupt, Act LED) and clocksx
Frame buffer (screen driver with escape sequences)limited
UART(s) (Polling and interrupt driver)x
System timer (with kernel timers)x
Platform DMA controllerDMA40 only
RP1 platform DMA controller (Raspberry Pi 5 only)x
EMMC SD card interface driverx
SDHOST SD card interface driver (Raspberry Pi 1-3)
PWM output (2 channels)4 channels
PWM sound output (on headphone jack)with adapter
I2C master(s) and slavemasters only
SPI0 master (Polling and DMA driver)x
SPI1 auxiliary master (Polling)
SPI3-6 masters of Raspberry Pi 4 (Polling)SPI1-3 and 5
SMI master
I2S sound output and inputx
HDMI sound output (without VCHIQ)x
Hardware random number generatorx
Watchdog devicex
Official Raspberry Pi touch screen (v1 only)
VCHIQ interface and audio service drivers
BCM54213PE Gigabit Ethernet NIC of Raspberry Pi 4
MACB / GEM Gigabit Ethernet NIC of Raspberry Pi 5x
Wireless LAN accessx
Driver for XPT2046-based touch screensx
NVMe SSD driver for Raspberry Pi 5 (experimental)x
USBHost controller interface (HCI) driversx
Standard hub driver (USB 2.0 only)x
HID class device drivers (keyboard, mouse, gamepad)x
Driver for on-board Ethernet device (SMSC951x)
Driver for on-board Ethernet device (LAN7800)
Driver for CDC Ethernet devices (RTL815x, QEMU)
Driver for USB mass storage devices (bulk only)x
Driver for USB floppy disk devices (experimental)x
Driver for USB audio streaming devices (RPi 4 only)x
Drivers for different USB serial devicesx
Audio class MIDI input supportx
Touchscreen driver (digitizer mode)x
Printer driverx
MIDI gadget driver
Serial CDC gadget driver
Mass-storage device gadget driver
File systemsInternal FAT driver (limited function)x
FatFs driver (full function, by ChaN)x
TCP/IP networkingProtocols: ARP, IP, ICMP, IGMP, UDP, TCPx
Clients: DHCP, DNS, NTP, HTTP, Syslog, MQTT, mDNSx
Servers: HTTP, TFTPx
BSD-like C++ socket APIx
GraphicsOpenGL ES 1.1 and 2.0, OpenVG 1.1, EGL 1.4
(not on Raspberry Pi 4)
uGUI (by Achim Doebler)
LVGL (by LVGL Kft)x
2D graphics class in base libraryx
Not supportedBluetooth

Support Status

This table lists the support status for the different Raspberry Pi models. Not listed models are not supported.

ModelStatusRemarks
Raspberry Pi Model AShould work
Raspberry Pi Model B R1Should work
Raspberry Pi Model B R2Tested
Raspberry Pi Model A+Tested
Raspberry Pi Model B+Tested
Raspberry Pi ZeroTested
Raspberry Pi Zero WTested
Raspberry Pi Zero 2 WTestedWLAN unknown for new revision
Raspberry Pi 2 Model BTested
Raspberry Pi 3 Model BTested
Raspberry Pi 3 Model A+Tested
Raspberry Pi 3 Model B+Tested
Raspberry Pi 4 Model BTested
Raspberry Pi 400Tested
Raspberry Pi 5TestedWith BCM2712 C1 and D0 steppings
Raspberry Pi 500Unknown
Compute ModuleReported to workUnknown which devices work
Compute Module 3Should work
Compute Module 3+Reported to workWLAN unknown
Compute Module 4TestedWLAN unknown
Compute Module 4SUnknown
Compute Module 5Reported to workUnknown which devices work
Compute Module ZeroReported to work

Build

For building 64-bit applications (AArch64) see the next section.

Circle does not support 32-bit applications on the Raspberry Pi 5.

This describes building on PC Linux. See the file doc/windows-build.txt for information about building on Windows. If building for the Raspberry Pi 1 you need a toolchain for the ARM1176JZF core (with EABI support). For Raspberry Pi 2/3/4 you need a toolchain with Cortex-A7/-A53/-A72 support. A toolchain, which works for all of these, can be downloaded here. Circle has been tested with the version 15.2.Rel1 (arm-gnu-toolchain-15.2.rel1-x86_64-arm-none-eabi.tar.xz) from this website. This is the recommended toolchain for AArch32 builds.

First edit the file Rules.mk and set the Raspberry Pi version (RASPPI, 1, 2, 3 or 4) and the PREFIX of your toolchain commands. Alternatively you can create a Config.mk file (which is ignored by git) and set the Raspberry Pi version and the PREFIX variable to the prefix of your compiler like this (don't forget the dash at the end):

RASPPI = 1
PREFIX = arm-none-eabi-

The following table gives support for selecting the right RASPPI value:

RASPPITargetModelsOptimized for
1kernel.imgA, B, A+, B+, Zero, (CM)ARM1176JZF-S
2kernel7.img2, 3, Zero 2, (CM3)Cortex-A7
3kernel8-32.img3, Zero 2, (CM3)Cortex-A53
4kernel7l.img4B, 400, CM4Cortex-A72

For a binary distribution you should do one build with RASPPI = 1, one with RASPPI = 2 and one build with RASPPI = 4 and include the created files kernel.img, kernel7.img and kernel7l.img. Optionally you can do a build with RASPPI = 3 and add the created file kernel8-32.img to provide an optimized version for the Raspberry Pi 3.

The configuration file Config.mk can be created using the configure tool too. Please enter ./configure -h for help on using it!

There are a number of configurable system options in the file include/circle/sysconfig.h. Please have a look into this file to learn, how you can configure Circle for your purposes. Some hardware configurations may require modifications to these options (e.g. using USB on the CM4).

Then go to the build root of Circle and do:

./makeall clean
./makeall

By default only the Circle libraries are built. To build a sample program after makeall go to its subdirectory and do make.

You can also build Circle on the Raspberry Pi itself (set PREFIX = (empty)) on Raspbian but you need some method to put the kernel.img file onto the SD(HC) card. With an external USB card reader on model B+ or Raspberry Pi 2/3/4 model B (4 USB ports) this should be no problem.

AArch64

Circle supports building 64-bit applications, which can be run on the Raspberry Pi 3, 4 or 5. There are also Raspberry Pi 2 versions and the Raspberry Pi Zero 2, which are based on the BCM2837 SoC. These Raspberry Pi versions can be used too (with RASPPI = 3).

The recommended toolchain to build 64-bit applications with Circle can be downloaded here. Circle has been tested with the version 15.2.Rel1 (arm-gnu-toolchain-15.2.rel1-x86_64-aarch64-none-elf.tar.xz) from this website. This is the recommended toolchain for AArch64 builds.

There are distro-provided toolchains on certain Linux platforms (e.g. g++-aarch64-linux-gnu on Ubuntu or gcc-c++-aarch64-linux-gnu on Fedora), which may work with Circle and can be a quick way to use it, but you have to test this by yourself. If you encounter problems (e.g. no reaction at all, link failure with external library) using a distro-provided toolchain, please try the recommended toolchain (see above) first, before reporting an issue.

First edit the file Rules.mk and set the Raspberry Pi architecture (AARCH, 32 or 64) and the PREFIX64 of your toolchain commands. The RASPPI variable has to be set to 3, 4 or 5 for AARCH = 64. Alternatively you can create a Config.mk file (which is ignored by git) and set the Raspberry Pi architecture and the PREFIX64 variable to the prefix of your compiler like this (don't forget the dash at the end):

AARCH = 64
RASPPI = 3
PREFIX64 = aarch64-none-elf-

The configuration file Config.mk can be created using the configure tool too. Please enter ./configure -h for help on using it!

Then go to the build root of Circle and do:

./makeall clean
./makeall

By default only the Circle libraries are built. To build a sample program after makeall go to its subdirectory and do make.

Installation

Copy the Raspberry Pi firmware (from boot/ directory, do make there to get them) files along with the kernel*.img (from sample/ subdirectory) to a SD(HC) card with FAT file system.

It is now always recommended to copy the file config32.txt (for 32-bit mode) or config64.txt (for 64-bit mode) from the boot/ directory to the SD(HC) card and to rename it to config.txt there. These files are especially required to enable FIQ use on the Raspberry Pi 4. Furthermore the additional file armstub7-rpi4.bin (for 32-bit mode) or armstub8-rpi4.bin (for 64-bit mode) is required on the SD card then. Please see boot/README for information on how to build these files.

Finally put the SD(HC) card into the Raspberry Pi.

Directories

  • include: The common header files, most class headers are in the include/circle/ subdirectory.
  • lib: The Circle class implementation and support files (other libraries are in subdirectories of lib/).
  • sample: Several sample applications using Circle in different subdirectories. The main function is implemented in the CKernel class.
  • addon: Contains contributed libraries and samples (has to be build manually).
  • app: Place your own applications here. If you have own libraries put them into app/lib/.
  • boot: Do make in this directory to get the Raspberry Pi firmware files required to boot.
  • doc: Additional documentation files.
  • test: Several test programs, which test different features of Circle.
  • tools: Tools for building Circle and for using Circle more comfortable (e.g. a serial bootloader).

Classes

The following C++ classes were added to Circle:

Scheduler library

  • CPipe: Unidirectional interprocess communication channel using a FIFO
  • CPipeFile: Read or Write endpoint of a CPipe channel

Net library

  • CNetBuffer: Generic frame/packet buffer for network protocol handling
  • CNetBufferQueue: FIFO queue for CNetBuffer objects
  • CReassemblyQueue: Reassembly queue for the TCP receiver

The available Circle classes are listed in the file doc/classes.txt. If you have Doxygen installed on your computer you can build a class documentation in doc/html/ using:

./makedoc

At the moment there are only a few classes described in detail for Doxygen.

Additional Topics

Trademarks

Raspberry Pi is a trademark of Raspberry Pi Ltd.

Linux is a trademark of Linus Torvalds.

PS3 and PS4 are registered trademarks of Sony Computer Entertainment Inc.

Windows, Xbox 360 and Xbox One are trademarks of the Microsoft group of companies.

Nintendo Switch is a trademark of Nintendo.

Khronos and OpenVG are trademarks of The Khronos Group Inc.

OpenGL ES is a trademark of Silicon Graphics Inc.

The micro:bit brand belongs to the Micro:bit Educational Foundation.

HDMI is a registered trademark of HDMI Licensing Administrator, Inc.