OpenHead Svenska

iPhone & iPad · Open source

A phone as your robot's face.

OpenHead turns an iPhone or iPad into an expressive robot head. Your robot, a Python script or an AI agent makes it smile, look around, talk and show things, over your own Wi-Fi.

Download on the App Store View on GitHub
QR code that opens OpenHead Robot Face on the App Store

Point the iPhone camera at the code to open the app on the App Store.

The iOS app OpenHead Robot Face for iPhone and iPad. The App Store page opens when the app is released; until then it is in beta on TestFlight.

A desk AI assistant

A 3D render of the bench rig: an iPhone 12 on the four-servo neck from Open Duck Mini. It follows your face, hears your question and answers in its own voice (turn the sound on), maps the room with the back camera while the front camera watches you, walks on Open Duck Mini knowing where it is, streams every sensor to your agent and shows it all in the cockpit in your browser. Video of the real rig comes next.

Build it yourself: printed parts, parts list, firmware and an MCP server for the neck are in OpenHead desk body (GitHub).

Everything a robot head needs

A phone already has the screen, sensors and radio. OpenHead makes them addressable from the rest of the robot, which needs to know nothing about iOS.

28 expressions

Happy, curious, thinking, surprised, worried, laughing, smug and more. Blend them, hold them for a moment, or layer a quick reaction on a mood.

Eyes that live

Look at any point on the screen or a direction from the head. Blinking, breathing and small eye movements keep the face alive between commands.

A mouth that talks

The robot streams how loud it speaks, 25 times a second, and the mouth follows within about 70 ms. Emotions are separate, so mood can change mid-sentence.

Talks and listens

From 0.4 the head speaks with its own voice, the mouth on the sound, and acts out cues in the text: [happy], [laugh], [pause]. The microphone turns what you say into text for your agent, on the device where it can.

Cockpit

From 0.5, openhead cockpit opens a dashboard in your browser: the head's camera as small video, every sensor, what it should say (with examples to start from), theme and emotion. Move, add and remove cards; your layout stays. The phone shows “Camera shared” while you watch.

Subtitles

Text on top of anything, for a robot without a speaker or an AI answer streaming in word by word. The mouth can move with the text.

Pictures, video, web

PNG, JPEG, animated GIF, WebP and SVG; H.264 video; web pages. Keep the face running in a corner while they show.

Camera view with HUD

See what the head sees, with a sci-fi heads-up display: boxes around faces, a locked target, compass, horizon, battery and your own lines.

Face tracking

Tracks several faces at once, with direction, size and place on screen, 15 times a second; with ARKit also the distance. The robot's eyes follow the person in front of it and keep eye contact.

Knows where it is

ARKit tracks the head's position and orientation in the room, 60 times a second, next to the motion sensors at up to 100 Hz. From 0.3, GPS, barometer, magnetometer and compass tell it where it is outside.

Three looks, one set of expressions

Themes are data, not code: shapes, colours and images in a folder. Every theme has the same 28 expressions, so the robot never has to care which one is on.

Cartoon theme: round eyes and a wide smile
Cartoon Round eyes, warm colours, a clear mouth.
Minimal theme: two glowing bars and a line
Minimal Two light bars and a line; few pixels, low power.
Halloween theme: glowing green jack-o'-lantern face
Halloween A glowing pumpkin grin, with an extra cackle.
See all 28 expressions in every theme

All expressions in the cartoon theme

All expressions in the minimal theme

All expressions in the halloween theme

See what the head sees

Show the front camera with a heads-up display drawn over it. The HUD marks every face, locks on the nearest one and shows the head's own readings. Four looks, all data like the face themes, so you can make your own.

Hunter HUD: red-tinted camera, white corner boxes, MATCH under the locked face, compass tape and analysis text
Hunter Red analysis view with a compass and MATCH on the target.
Camcorder HUD: green REC, PLAYBACK, timecode, battery and a crosshair on the locked face
Camcorder REC, PLAYBACK, timecode and battery.
Flight HUD: compass tape, artificial horizon, battery, pitch, roll and position
Flight Compass, artificial horizon, tilt and position.

On a real phone

Screenshots from an iPhone 18 Pro: the box sits on the face it found, the eyes follow it, and the phone's own battery, heading and tilt are on the HUD.

Hunter HUD on an iPhone: red camera view, a box locked on a person's face, MATCH, compass heading 095, battery 60 percent Flight HUD on an iPhone: crosshair on a person's face, compass 058, artificial horizon, pitch 17.6 degrees, battery 60 percent Camcorder HUD on an iPhone: crosshair on a person's face, the robot's own lines TASK SAY HELLO and SPEED 0.4 M/S, the face in the corner Boot HUD on an iPhone: boot text, corners locked on a person's face, LOCK, heading and tilt

Put your own information on it

  • Built-in values: battery, temperature, compass heading, pitch and roll, position, faces in view, the locked target.
  • Instruments: compass tape, artificial horizon, battery gauge.
  • Your robot adds its own values and lines at any time, such as task, speed or destination.
  • A HUD theme is a small JSON file: colours, tint, scanlines, boxes, lock, text blocks and instruments.
Camcorder HUD with the robot's own lines: TASK DELIVER CUP, SPEED 0.4 M/S, and a compass
# the robot's own lines on the HUD
openhead camera camcorder --follow
openhead hud --set task="DELIVER CUP" --set speed=0.4 \
  --line "TASK {task}" --line "SPEED {speed} M/S" --widget compass

Sensor data

Everything the head senses arrives as small JSON messages you subscribe to, at the rate you ask for. Angles follow the head: + to its left and up; motion follows ROS conventions. The charts below are a 15-second recording from an iPhone 18 Pro held in the hand, with one person in front of it (tools/sensor_plots.py records any head).

Line chart: pitch and roll of the phone in degrees over fifteen seconds; pitch drifts between 5 and 22 degrees
Line chart: acceleration x, y and z; x stays near 9.8 because the phone stands in landscape
Line chart: bearing of one face between 5 and 14 degrees as the person moves
Path of the phone seen from above, from ARKit: a walk of about 8 metres

Data: imu.csv · faces.csv · pose.csv · more charts: rotation rate, position over time.

Every sensor the head uses

An iPhone 12 already carries these. OpenHead reads them and streams the results; nothing else needs to be wired to the robot.

SensorWhat OpenHead does with itStream
Front camera (TrueDepth)face tracking: finds several faces; with ARKit, follows one face with its distancefaces, camera view
Back cameraARKit world tracking (visual-inertial SLAM): where the head is in the room and how it is turnedpose
Accelerometer and gyroscopeorientation, rotation rate and acceleration in ROS conventions; tilt on the HUDimu
Magnetometermagnetic field and compass heading (true north with location access)env
Barometerair pressure and altitude changeenv
GNSS: GPS, GLONASS, Galileo, QZSS, BeiDoulatitude, longitude, altitude, accuracy, speed and coursegps
Microphone (from 0.4)speech to text, on the device when it can; the head looks attentive while you talkspeech
Speaker (from 0.4)the head's own voice, with the mouth moving to the sound and expressions in the right placesspeech.say
Battery and temperaturebattery level, charging and thermal statestatus

From 0.4 the microphone and the speaker too: the head speaks with its own voice and turns what you say into text. Not used: the proximity sensor (it turns the screen off and would hide the face) and the ambient light sensor (no public API). The iPhone 12 has no LiDAR, and OpenHead needs none. From 0.5, as options on Pro models only: LiDAR depth for exact distances, and a 3D mesh of the room.

StreamRateFieldsWhen
imuup to 100 Hzorientation (quaternion), rotation rate, acceleration, sensor timealways
faces15 Hzid, bearing, elevation, size, confidence, box on screen, locked; distance with ARKitmodes capture and sensing
poseup to 60 Hzposition (m), orientation, tracking state and reasonmode sensing (ARKit)
gps1 Hzlatitude, longitude, altitude, accuracy, speed, coursefrom 0.3; after the user allows location access
envup to 10 Hzair pressure, altitude change, magnetic field, compass heading and accuracyfrom 0.3; the barometer after Motion & Fitness access
status1 Hzbattery, charging, thermal state, view, theme, emotion, mode, faces, clientsalways
logas it happenslevel, subsystem, messagealways (dev mode to read history)
cameraup to 10 Hzsmall JPEG frame, width, height, front or back camerafrom 0.5; modes capture and sensing, “Camera shared” on the phone
meshup to 1 Hzroom mesh anchors that changed (LiDAR)from 0.5; Pro models only, optional

Two camera modes, because ARKit owns the cameras: capture shows the front camera and finds several faces; sensing runs ARKit for the head's position in the room and follows one face with the depth camera.

Cockpit

From 0.5, one command opens a dashboard for the head in your browser: what its cameras see, every sensor, what it should say, its theme and its mood. Nothing to install beyond the Python tools; the page runs on your computer and talks only to your head.

OpenHead cockpit in a browser: the camera as video with two people, a Speak card with the joke from the film and example buttons, expression and theme, listen, status, mode and ARKit position

Both cameras

Low-resolution video, 160 to 640 pixels, 1 to 10 frames a second. Mode capture shows the front camera with the faces it finds; mode sensing shows the back camera that ARKit tracks the room with. The phone shows “Camera shared” the whole time anyone watches, and no frame is stored.

Talk through it

Type what the head should say, with cues such as [happy] and [laugh], or start from an example: the joke from the film, a greeting, a meeting reminder. Listen shows what the microphone hears, word by word.

Your own layout

Every function is a card: camera, speak, listen, expression and theme, status, ARKit map, IMU, compass and air pressure, GPS, faces, log, LiDAR on Pro models. Drag them, add and remove them; the browser remembers your layout, and Reset layout brings back the default.

openhead cockpit --device 192.168.1.20      # or: openhead viewer
openhead sim --pro                          # try it without a phone

How it works

The phone sits on the robot in landscape. Everything stays on your local network: no accounts, no cloud.

  1. Mount and open

    Put the phone on the robot in landscape and open the app. The face appears straight away.

  2. Pair once

    A controller on the same Wi-Fi finds the head and asks to pair; you type the 6-digit code shown on the screen.

  3. Drive it

    Expressions, gaze, speech, subtitles, images and video arrive as small JSON commands over a WebSocket.

  4. Check it

    In dev mode, screenshots and logs show exactly what the head did, for you or an AI agent.

Settings: name, port and network addresses Settings: theme when offline, motion sensor mounting, dev mode Settings: dev mode and paired clients Settings: version, protocol and device

Settings on the device

  • Long-press the face for 1.5 seconds to open them.
  • Name and port, the theme shown when nothing is connected, and how the phone is mounted.
  • See every paired controller and revoke any of them.
  • Dev mode allows screenshots, logs and diagnostics over the network; leave it off on a robot in use.

Built for developers and AI agents

The protocol is the product: JSON over WebSocket with a published schema. Around it:

  • A Python client and the openhead command line tool.
  • A desktop simulator that speaks the same protocol, to develop before a servo moves.
  • YAML scenarios with golden screenshots, run on the simulator and on the phone.
  • An MCP server, so an AI agent can drive the head and check its work.
  • Apache 2.0. Source on GitHub.
# install the tools from the Git tag
uv add "openhead @ git+https://github.com/PatrikBichis/openhead@v0.4.0#subdirectory=python"

# find the head and pair (type the code on screen)
openhead discover
openhead pair --device 192.168.1.20

# make it do things
openhead emotion curious
openhead subtitle "Hello! I write when I can't speak." --mouth
openhead show clip.mp4 --overlay face-corner
openhead camera hunter --follow
openhead watch faces -n 5

Use it from an AI agent

OpenHead includes an MCP server, so an AI agent can drive the head and check its own work: emotions, subtitles, the camera with a HUD, who is in front of it, GPS and compass, screenshots. It runs on your computer and talks to the phone over Wi-Fi. You need uv and the head's address from the app's settings (or auto).

Claude Code

In a terminal:

claude mcp add openhead --scope user -- uvx --from "openhead[mcp] @ git+https://github.com/PatrikBichis/openhead@v0.4.0#subdirectory=python" openhead mcp --device 192.168.1.20
Claude Desktop

Settings → Developer → Edit Config (claude_desktop_config.json), then restart. If uvx is not found, give its full path.

{
  "mcpServers": {
    "openhead": {
      "command": "uvx",
      "args": ["--from", "openhead[mcp] @ git+https://github.com/PatrikBichis/openhead@v0.4.0#subdirectory=python", "openhead", "mcp", "--device", "192.168.1.20"]
    }
  }
}
Codex CLI

In a terminal, or in ~/.codex/config.toml:

codex mcp add openhead -- uvx --from "openhead[mcp] @ git+https://github.com/PatrikBichis/openhead@v0.4.0#subdirectory=python" openhead mcp --device 192.168.1.20

# or ~/.codex/config.toml
[mcp_servers.openhead]
command = "uvx"
args = ["--from", "openhead[mcp] @ git+https://github.com/PatrikBichis/openhead@v0.4.0#subdirectory=python", "openhead", "mcp", "--device", "192.168.1.20"]
Cursor and Gemini CLI

Cursor: ~/.cursor/mcp.json. Gemini CLI: ~/.gemini/settings.json. The same block as Claude Desktop:

{
  "mcpServers": {
    "openhead": {
      "command": "uvx",
      "args": ["--from", "openhead[mcp] @ git+https://github.com/PatrikBichis/openhead@v0.4.0#subdirectory=python", "openhead", "mcp", "--device", "192.168.1.20"]
    }
  }
}
VS Code with GitHub Copilot

Agent mode, .vscode/mcp.json:

{
  "servers": {
    "openhead": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "openhead[mcp] @ git+https://github.com/PatrikBichis/openhead@v0.4.0#subdirectory=python", "openhead", "mcp", "--device", "192.168.1.20"]
    }
  }
}
Over the network (HTTP)

For an agent on another machine: run the server on the robot's computer with a token. Without --token it only listens on 127.0.0.1.

openhead mcp --http 0.0.0.0:8800 --token "$(openssl rand -hex 16)" --device 192.168.1.20

# Claude Code on the other machine
claude mcp add --transport http openhead http://robot-pc.local:8800/mcp --header "Authorization: Bearer <token>"

First time: ask the agent to pair with the head and read it the 6-digit code on the phone. Then try “Look curious and write Hello as a subtitle”, “Show the camera with the hunter HUD; how many people do you see?” or “Which way is the head facing, and what is the air pressure?”

Questions

Does the app work on its own?

It shows the face and stays alive with blinking and breathing, but it is meant to be driven: by your robot's computer, a script or an AI agent on the same network.

Which devices are supported?

iPhone 12 or newer and iPads with iPadOS 17 or later. iPhone 12 is the baseline every feature is built and tested for.

Does it collect any data?

No. Nothing leaves your local network and there are no accounts, analytics or ads. Location and sensor readings go only to the controllers you paired, and only when they ask. See the privacy policy.

Does the camera record or send video?

No. The camera only runs when a paired controller asks for it, images are processed on the phone and never stored or sent. Only positions and angles of faces leave the phone, and nobody is identified. See the privacy policy.

Can I use it with ROS 2?

Yes, through a bridge built on the Python client. The head knows nothing about the robot's body; the robot owns its kinematics.