OsmoWeb

OsmoWeb is an open-source TypeScript library that brings Osmocom’s mobile communication capabilities to the web.

⚠️ This project is under active development. Not all features are implemented yet and some functionality may not work.

Description

OsmoWeb is a TypeScript monorepo for building web apps and services around Osmocom network elements, with a long‑term goal of providing an npm package to run a 2G base station in the browser or in a web environment.

What we are building:

• Web BTS: osmo-bts-trx compiled to WebAssembly (WASM), with its UDP network layer replaced by WebSocket. This enables running the BTS in the browser or WASI while talking to native Osmocom services through a bridge.

• Transport bridge: a WebSocket ↔ UDP router in backend-core that connects the browser-based BTS to the native Osmocom stack (osmo-bsc, osmo-msc, osmo-hlr, osmo-mgw).

• Frontend helpers: frontend-core adds client-side utilities for the WASM BTS transport and device handling.

• UI components: a small Vue 3 set for demos and apps, including log viewer, BTS configuration panel, and WebUSB SDR selection.

Responsibilities by package:

• core — shared types and utilities.

• backend-core — WebSocket ⇄ UDP router for Osmocom services, stats and log collection, and service management (e.g., BTS params, subscribers, etc.). All Osmocom services except the WASM osmo-bts-trx remain native.

• nestjs-microservice — NestJS integration that wraps backend-core into DI-ready providers and WebSocket gateways.

• frontend-core and vue3-components — client-side helpers and reusable UI for dashboards and demos.

Use cases:

• Browser-based labs and demos for SDR/Osmocom.

• Web dashboards for BSC/MSC/HLR/MGW state, logs, and control.

• Automation of routine network operations.

This project builds on existing Osmocom services; it does not replace them. Focus areas are developer ergonomics, type safety, and real-time streaming UX.

Project structure

Monorepo packages and test apps:

.
├─ packages/
│  ├─ core/                – Shared domain types, utilities, constants
│  ├─ backend-core/        – Backend router/controllers and common types for Osmocom services
│  ├─ nestjs-microservice/ – NestJS module + gateways built on top of backend-core
│  ├─ frontend-core/       – Front-end utilities and client-side helpers
│  └─ vue3-components/     – Reusable Vue 3 UI components and styles
├─ test-apps/              – Small scripts to manually test integrations with Osmo services
└─ ...

• packages/core — Core shared library with domain types, utilities, and constants used across all packages. Docs: @osmoweb/core

• packages/backend-core — Backend building blocks: router and controllers to talk to Osmocom daemons. Docs: @osmoweb/backend-core

• packages/nestjs-microservice — NestJS integration that wraps backend-core into DI-ready providers and WebSocket gateways; configurable via OSMO_* env vars. Docs: @osmoweb/nestjs-microservice

• packages/frontend-core — Front-end core utilities and adapters for client apps. Docs: @osmoweb/frontend-core

• packages/vue3-components — Vue 3 UI components and styles used by OsmoWeb apps (BTS config/input components). Docs: @osmoweb/vue3-components

• test-apps — Sample scripts for manual testing (e.g., bsc-test.ts, msc-test.ts, hlr-test.ts, mgw-test.ts).

Documentation

• Docs index: docs/README.md

• Architecture entry point: docs/architecture/overview.md

Setup the project

npm install

Build the project

Build

npm run build

Run tests

Run unit tests for each workspace

npm run test

Run all tests

npm run test:all

Run all tests and watch for changes

npm run test:watch

Run coverage check

npm run test:coverage

Run test applications

Test apps documentation: test-apps/README.md

All test applications are located in the test-apps folder. Before running any of them, change into that directory:

cd test-apps

Run the BSC test application:

npm run test:bsc

Run the HLR test application:

npm run test:hlr

Run the MGW test application:

npm run test:mgw

Run the MSC test application:

npm run test:msc

Note: Ensure the required Osmocom services are reachable before running the tests.

Docker infrastructure

Monitoring stack (Prometheus/Pushgateway/Alertmanager + InfluxDB + Grafana):

• docker/README.md

Environments

License

OsmoWeb is MIT licensed