@osmoweb/core

Shared, dependency-light utilities and domain types used across the OsmoWeb monorepo.

Today, the package focuses on:

  • Radio helpers: ARFCN ⇄ frequency conversions and band detection for GSM / LTE / NR.

  • Osmo helpers: small utilities that adapt Osmocom concepts to the rest of the stack (e.g., log level mapping).

Install

npm install @osmoweb/core

Imports (entrypoints)

This package is published with subpath exports:

  • @osmoweb/core — re-exports everything from radio and osmo

  • @osmoweb/core/radio — radio band/ARFCN/frequency helpers

  • @osmoweb/core/osmo — Osmocom-related helpers

In most apps you’ll want the more specific entrypoints to keep imports explicit:

import { configureARFCN, RadioTechnology, LTEBand } from '@osmoweb/core/radio';
import { getJournalLogLevelFromOsmoLogLevel } from '@osmoweb/core/osmo';

Units

All frequencies in this package are expressed in kHz.

Radio

configureARFCN()

A universal helper that takes either an ARFCN or a frequency (kHz) and returns a complete configuration:

  • detects technology and band when possible

  • computes uplinkFrequency and downlinkFrequency (kHz)

  • frequency can be either uplink or downlink; the helper will normalize it by recomputing both sides

import {
  configureARFCN,
  RadioTechnology,
  LTEBand,
} from '@osmoweb/core/radio';

// 1) Provide ARFCN (highest priority)
const cfg1 = configureARFCN({
  technology: RadioTechnology.LTE,
  band: LTEBand.B3,
  arfcn: 1300,
});

// cfg1.uplinkFrequency / cfg1.downlinkFrequency are in kHz

// 2) Provide frequency (kHz) and let band auto-detect
const cfg2 = configureARFCN({
  technology: RadioTechnology.GSM,
  frequency: 935_200, // kHz
});

// cfg2.arfcn is computed and frequencies are normalized

Low-level conversions

If you already know the technology and band, you can call the specific helpers.

import {
  GSMBand,
  LTEBand,
  NRBand,
  gsmArfcnToFrequency,
  gsmFrequencyToArfcn,
  lteArfcnToFrequency,
  nrFrequencyToArfcn,
} from '@osmoweb/core/radio';

const gsm = gsmArfcnToFrequency(0, GSMBand.GSM_900);
// -> { uplink: number, downlink: number } (kHz)

const arfcn = gsmFrequencyToArfcn(935_200, GSMBand.GSM_900);

const lte = lteArfcnToFrequency(1200, LTEBand.B3);

const nrArfcn = nrFrequencyToArfcn(3_500_000, NRBand.N78);

Detection & ranges

import {
  RadioTechnology,
  getSupportedBands,
  getBandArfcnRange,
  getBandFrequencyRange,
  detectGSMBandFromFrequency,
} from '@osmoweb/core/radio';

const lteBands = getSupportedBands(RadioTechnology.LTE);

const gsm900Candidates = detectGSMBandFromFrequency(935_200);

const range = getBandArfcnRange(RadioTechnology.GSM, gsm900Candidates[0]);
const freqs = getBandFrequencyRange(RadioTechnology.GSM, gsm900Candidates[0]);

Osmo

getJournalLogLevelFromOsmoLogLevel()

Maps Osmocom log levels (numeric) to JournalLogLevel from @websdr/core/utils.

import { getJournalLogLevelFromOsmoLogLevel } from '@osmoweb/core/osmo';

const level = getJournalLogLevelFromOsmoLogLevel(7);
// 7 (LOGL_ERROR) -> JournalLogLevel.ERROR

API overview

Everything below is exported from @osmoweb/core/radio:

  • Enums: RadioTechnology, GSMBand, LTEBand, NRBand

  • Types: MobileBand, ARFCNConfigInput, ARFCNConfig, FrequencyResult

  • Universal: configureARFCN(), getSupportedBands(), getBandArfcnRange(), getBandFrequencyRange()

  • GSM: gsmArfcnToFrequency(), gsmFrequencyToArfcn(), detectGSMBandFromFrequency(), detectGSMBandFromArfcn(), getGSMBandArfcnRange(), getGSMBandFrequencyRange(), getAllGSMBands()

  • LTE: lteArfcnToFrequency(), lteFrequencyToArfcn(), detectLTEBandFromFrequency(), detectLTEBandFromArfcn(), getLTEBandArfcnRange(), getLTEBandFrequencyRange(), getAllLTEBands()

  • NR: nrArfcnToFrequency(), nrFrequencyToArfcn(), detectNRBandFromFrequency(), detectNRBandFromArfcn(), getNRBandArfcnRange(), getNRBandFrequencyRange(), getAllNRBands()

Everything below is exported from @osmoweb/core/osmo:

  • getJournalLogLevelFromOsmoLogLevel()

Compatibility notes

  • TypeScript: ships *.d.ts typings.

Development (monorepo)

From the repository root:

npm install
npm run build
npm test --workspace=packages/core

From this package folder:

Build

npm run build

Test

npm test

License

OsmoWeb is MIT licensed