Orbit OS examples for Java

Small, single-file apps that show how to use the Orbit OS API from Java — one feature per example.

This repository is a collection of example apps for Orbit OS, built with the Orbit OS SDK for Java. Each example folder is a separate Orbit Studio project, with the same layout as a project created in Orbit Studio: open one folder, run it, deploy it.

Each example is a complete app with its own App.java, metadata.json manifest and project settings. Read one, run it, then copy the folder as the start of your own app.

Runs on Raspberry Pi, Arduino UNO Q and other ARM64 devices with Orbit OS (free Community Edition).

Examples

The examples are grouped in folders by topic.

Getting started — getting-started/

Start here.

Example	What it shows	Services used
template	The smallest possible app. Copy it to start a new one	System
basic	Connect to the device and read system information: API version, device identity, hardware, OS	System

System — system/

Information about the device and its state.

Example	What it shows	Services used
metrics_info	Read one snapshot of CPU, memory, disk and temperature metrics	System
device_certification	Check whether the app runs on certified hardware and read the certification serial	System

Peripherals — peripherals/

Pins, buses and serial ports.

Example	What it shows	Services used
gpio_output	List the GPIO lines and blink the first one	GPIO
gpio_input	Wait for an input pin (GPIO24) to go high	GPIO
pwm	List the PWM channels and set frequency and duty cycle on the first one	PWM
i2c	List the I2C buses, read the configuration and scan for devices	I2C
spi	List the SPI devices, read the configuration and run a full-duplex transfer	SPI
uart	Open a serial port and print what it receives	UART
gpio_button_led	Read a button on an input pin and drive an LED on an output pin with it	GPIO
pwm_fade	Raise and lower the duty cycle step by step, like an LED fading in and out, then stop the output	PWM

Network — network/

Network interfaces of the device.

Example	What it shows	Services used
wifi_scan	List the WiFi interfaces and scan for networks	WiFi
eth_status	List the Ethernet interfaces with link state and IP configuration	Ethernet
wifi_status	Show, for each WiFi interface, whether it is connected, its mode and the details of the connection	WiFi

Notifications — notifications/

Push notifications to the owner's phone. Needs internet access and an Orbit OS account on the device.

Example	What it shows	Services used
mobile_notification	Send a push notification to the phones linked to the device owner's account	Mobile notifications
notification_options	Send a push notification with the optional fields: data for the mobile app, a collapse key and a time to live	Mobile notifications

Media and AI — media-ai/

Cameras. Examples of on-device inference will be added here.

Example	What it shows	Services used
camera_snapshot	List the cameras, take one picture with the first one and save it to a file	Camera

Web interface — web-ui/

Apps with a page in the Orbit OS Launcher.

Example	What it shows	Services used
hello_web	Serve a web page through the Orbit OS Launcher, behind the device login	System, AppHub

mobile_notification, notification_options and device_certification use features added in API 26.1. They need a device with API 26.1 or newer; the other examples also run on API 26.0.

The hardware examples (gpio_*, pwm*, i2c, spi, uart, camera_snapshot) use the pins, buses and ports set as constants at the top of each App.java. Change them to match your board and wiring before you run.

Run an example

Recommended: Orbit Studio (VS Code).

You need VS Code with the Orbit Studio extension, a Java 17 JDK (for example Eclipse Temurin) installed, and a device with Orbit OS in Developer Mode.

1. Clone the repository and open the folder of one example in VS Code (not the repository root):

   git clone https://github.com/OrbitOS-org/orbit-os-sdk-examples-java
   code orbit-os-sdk-examples-java/peripherals/gpio_output

2. In the Orbit sidebar, run Add / Update SDK and set your device's IP. Orbit Studio downloads the SDK into orbit-os-sdk-java/.
3. Use Run to try it live: the example runs on your computer and talks to the device.
4. Use Build + Deploy to install the signed .orb on the device.

Without Orbit Studio: each example builds against the SDK copy in its orbit-os-sdk-java/ folder, which is not in the repository (Orbit Studio downloads it). Unpack the SDK release into that folder, put the development certificates in certs/grpc/, then:

cd orbit-os-sdk-examples-java/getting-started/basic
./gradlew :apps:basic:run --args=<device IP>

Use Orbit Studio to package and sign the .orb.

How an example is built

<topic>/<example>/apps/<example>/src/main/java/…/App.java              the app
<topic>/<example>/apps/<example>/src/main/resources/metadata.json      manifest: name, version, entry point, permissions
<topic>/<example>/apps/<example>/orb/icon.svg                          launcher icon
<topic>/<example>/apps/<example>/build.gradle, proguard-rules.pro      app build: one JAR with the SDK inside
<topic>/<example>/build.gradle, settings.gradle, gradlew               Gradle project, using the local SDK copy
<topic>/<example>/orbit.project.json                                   Orbit Studio project settings
<topic>/<example>/certs/grpc/                                          development certificates (added by Orbit Studio, not committed)
<topic>/<example>/orbit-os-sdk-java/                                   the SDK (downloaded by Orbit Studio, not committed)

• One client. Every example creates a client with Client.connect(host, name) and closes it at the end. On the device it connects locally. The device address, the first argument, is only used in development, when the example runs on your computer.
• Permissions. metadata.json lists the services the app may call, such as GpioService/*. Orbit OS refuses calls to any service that is not listed, so each example declares only what it uses.
• SDK version. sdkVersion in each example's orbit.project.json is v26.1.0: that is the SDK Orbit Studio downloads into orbit-os-sdk-java/, and settings.gradle builds the app against that local copy.

Write your own app

Copy the getting-started/template folder, rename it, its apps/template folder and the Java package, and update orbit.project.json (name, appPath), settings.gradle (rootProject.name), apps/<name>/build.gradle (main class, JAR name), proguard-rules.pro and metadata.json (name, entry_point, package_id, permissions) to the new name. Then add the calls you need from the example closest to what you want to build.

For complete apps with a web interface, see the app repositories of the Orbit OS organization.

Links

Orbit OS · Getting started · SDK reference · Orbit OS SDK for Java · info@orbit-os.org

License

Apache-2.0 — see LICENSE and NOTICE.