Login
social-badge
Login

social-badge is software for a wearable badge that lets people send short messages to each other on a system they can run, read and change themselves. It is written in Crystal and runs on BeagleBadge, a small Linux computer from BeagleBoard.org that is worn on a lanyard, and on ordinary servers.

What it's for

Many people rely on Facebook to keep in touch with friends and family. social-badge asks whether something can connect them even better while staying in their hands. A badge passes short messages directly from one person to another by radio, so no internet connection is needed. When there is an internet connection, the same messages can also reach people on the Fediverse: the network of independent social sites, such as Mastodon servers, that exchange posts with each other. Those sites are run by others; the badge and its own server are not.

What it's made of

How it's shaped

One program runs on each badge and on each server. It serves a web page for writing messages and an HTTP API (requests that other programs send to it, by default on port 30000) for reading and posting them. On a badge it also draws the badge's screen. A message is also called a post. Each person's timeline is the list of posts they have written and received.

What success looks like

Each item says where it stands and links to the evidence.

  1. A public server. A server shows public posts on the web. Running at badge.beagle.group. Which version it runs hasn't been checked since Nov 3.
  2. Runs on BeagleBadge. The program is built for BeagleBadge and runs on it. Built, not yet run: the build is checked (post 6b26b45ec7), but the badge itself isn't booting (post 8478db6c9a). The build was made by hand rather than by OCX (see below), a shortcut to be replaced (ticket e4eb4e1582).
  3. Two badges by radio. Two badges exchange posts over Meshtastic. Not yet: no real radio has carried a post.
  4. Badges synced by Fossil. Badge timelines live in Fossil repositories and sync with each other. Not yet (ticket 0b0735b023).
  5. Seen on Mastodon. A post written on a badge or server is visible from a real Mastodon account. Not yet shown: the ActivityPub code is written and tested, but no real Mastodon account has seen a post.
  6. iPhone through Stone. A badge exchanges messages with an iPhone running Stone. Not yet: nothing for it is written.

The virtues behind it

social-badge is one of a group of projects that share a workbench called OCX, which runs their builds and their AI agent sessions across several machines. OCX's code is kept in a Fossil repository named ollama. The Big Picture page says why each project is in the group. Every project follows the same four virtues:

Run it

You need Crystal and its package tool, shards. The libraries the program uses (Crystal calls them shards) aren't stored in this repository; the file shard.lock pins their versions. Two of them run an extra setup step after download: the lvgl shard's needs SDL2, a desktop graphics library, and the typst shard's needs cargo, Rust's build tool. Many machines lack them, so skip those steps and build LVGL with the project's own script, which uses SDL2 only if it's installed:

shards install --frozen --skip-postinstall --skip-executables
crystal run scripts/build_liblvgl.cr
crystal run src/main.cr

Then open http://127.0.0.1:30000/health, which answers with a short JSON status. The web page and the badge screen run from the same process. With no screen attached, the program uses LVGL's headless mode, which draws to memory instead of a display; set SOCIAL_BADGE_LOCAL_UI=1 to use a real screen.

The browser preview needs a typst program on your PATH (see docs/typst-runtime.md). Without one, /health reports the preview as unavailable, and everything else still works.

More detail