Configuration Reference

Run the integrated runtime with a config directory:

cargo run --release -p cdma-nib -- --config-dir config

Runtime Flags

The launcher starts every component as a separate process. Each one reads its own file from the config directory, so a component can also run on its own host with just that file.

Defaults in this reference

The Default column shows the value in the shipped config/*.json. Where the shipped file omits a key, the column shows the built-in default that applies when the key is absent.

Local Overrides

Every per-node config in config/ supports a sibling <name>.local.json file that is merged on top of the base file at load time:

config/bts.json          # shared default (checked into git)
config/bts.local.json    # your overrides (gitignored)

The runtime reads the base file, deep-merges the local file on top, and validates the result. The local file only needs the fields you are changing.

Applies to: bts.json, bsc.json, msc.json, pcf.json, pdsn.json, hlr.json, smsc.json, management.json, voice-gw.json, and standalone radio profile files (e.g. radio_bladerf_micro2.local.json). events.json has no local override.

Merge behavior:

• Nested objects merge field by field; omitted fields keep the base value.
• Arrays in the local file replace the base array (no append).
• Setting a field to null removes it, falling back to the struct default.

Example config/bts.local.json retuning to a different CDMA channel and raising TX gain:

{
  "channel": {
    "band_class": "bc0",
    "cdma_channel": 283
  },
  "radio": {
    "tx_gain_db": 60
  }
}

See Configuration → Local Overrides for the introductory walkthrough.

See Carrier Profiles for the Verizon and Sprint startup commands, local override order, and Sprint-specific tuning. Profile names may contain lowercase letters, digits, and hyphens. A profile also supports a sibling bts.<profile>.local.json override.

bts.json

BTS radio and PHY configuration. One file per cell.

Top-level

channel

Single source of truth for the BTS’s RF tuning, per C.S0057-F. The BTS derives TX/RX center frequencies and the broadcast CDMA_FREQ / BAND_CLASS fields from this triple.

See Channel Planning for the full band-class table, valid channel ranges, and recommended channels, or use the CDMA Channel Calculator to look up the TX/RX frequencies for any (band, subclass, N).

Overrides for loopback or development work:

• runtime.tx_freq_hz_override (integer, optional) — force the TX center frequency.

evdo

Optional EV-DO / HRPD Rev 0/Rev A carrier configuration. The HRPD access network (AN) runs inside the BTS, so enabling EV-DO on a cell also starts that cell’s AN and its A8/A9 link to the PCF. See the EV-DO guide.

Use a normal SDR radio profile with this section. The old HRPD-specific radio profiles and dual-RF evdo_rf settings have been removed.

Derived RF profile

The BTS derives TX/RX SDR sample rates and RF bandwidths at startup from channel and evdo.

HRPD-only mode also selects the HRPD reverse carrier automatically and omits all 1x receiver correlator and traffic chains.

Composite mode validates both forward and reverse carrier spacing. If the configured 1x and HRPD channels do not fit within the 16x cap, startup fails with a configuration error.

overhead

Cell identity and system parameters broadcast on the paging channel.

timezone

Optional. Controls the local time broadcast on both 1x and EV-DO. Use source = "system" for the host timezone, source = "user" for a named IANA timezone, or source = "overhead" for the static overhead values. System and user timezones pick up DST changes without a restart.

source = "system" reads the host’s IANA zone. The BTS refuses to start if the host has no IANA zone configured and source = "system" is selected.

source = "user" requires a parseable IANA name (e.g. "America/Los_Angeles"). Invalid names are rejected at config load.

DAYLT tells a 1x phone that daylight saving time is active. It does not tell the phone to add or subtract another hour. The UTC offset already includes the DST adjustment.

LP_SEC is not driven by this section. It lives on overhead.lp_sec and is broadcast as the leap-second value on both 1x and HRPD regardless of source.

Examples:

"timezone": { "source": "overhead" }

"timezone": { "source": "system" }

"timezone": { "source": "user", "tz": "America/Los_Angeles" }

runtime

PHY/MAC/LAC runtime settings.

runtime.realtime

Controls scheduling for the BTS TX, RX, and radio-driver threads. Failures are reported in the logs and radio metrics; the BTS continues with the scheduling policy the operating system permits.

Linux requires permission to select SCHED_FIFO, normally through the process’s real-time priority resource limit or CAP_SYS_NICE. On macOS the priority numbers and CPU fields do not apply; the runtime requests the platform’s time-constraint or interactive QoS classes instead.

runtime.downlink.pilot

runtime.downlink.sync

runtime.downlink.paging

runtime.downlink.traffic

The four power_fraction values follow the C.S0010 base station test model and must not sum to more than 1.0. Pilot, sync, and paging power stay fixed as calls come and go. The BTS logs the split in percent and dB at startup.

runtime.downlink.paging.message_defaults

Overhead messages broadcast on the paging channel. schedule controls which messages are transmitted and in what order.

The serving band chooses the neighbor-list format automatically. Band Class 0 uses neighbor_list. Every other band uses extended_neighbor_list. Band Class 1 and Band Class 4 also receive the required base-class indicator. The runtime adds the appropriate neighbor message if it is missing from schedule.

extended_system_parameters — IMSI defaults and soft-handoff thresholds:

system_parameters — core cell parameters:

access_parameters — reverse access channel configuration:

neighbor_list — Band Class 0 neighbor pilots:

extended_neighbor_list — neighbor records for other bands:

Each extended record contains nghbr_config (0..3), nghbr_pn (0..511), and search_priority (0..3). To put a neighbor on another carrier, provide both nghbr_band (0..31) and nghbr_freq (0..2047). Omit both for a neighbor on the current carrier.

cdma_channel_list — channels (integer array, []): extra CDMA channel numbers advertised in the CDMA Channel List Message. The serving channel is always included.

general_page and order hold the defaults for General Page and Order messages the BTS builds. Leave them at their shipped values.

runtime.uplink

Reverse link configuration.

runtime.overhead

Overhead channel scheduling.

abis

Abis TCP signaling address (BTS side).

bearer

Abis UDP bearer addressing (BTS side).

management

The operations endpoint the BSC enrolls this cell through. See the Multiple Cells guide.

paging_retry

Page retransmission budget. The BTS supplies these values to the BSC at enrollment.

abis_timers

BTS-side Abis timers per A.S0003-A §8 Table 8-1, in milliseconds. Not present in the shipped file.

bsc.json

BSC radio access control and paging policy.

traffic_assignment

f_sch_rate_bps is only used when enable_f_sch is true. 9600 is the fundamental-channel data rate, not a valid F-SCH rate.

This is a carrier-wide packet-data setting: every eligible SO33 packet session gets the configured F-SCH rate.

traffic_retry

paging_retry no longer belongs here. Set it in bts.json. The BSC takes the value from each cell at enrollment.

abis_timers

BSC-side Abis timers per A.S0003-A §8 Table 8-1. Granularity is 100 ms and ranges are 0–1000 ms except tsetupb_ms (0–500). Not present in the shipped file.

bts_peers

The cells this BSC serves — one entry per BTS. The BSC enrolls each peer over its operations endpoint, then brings up Abis to it. See the Multiple Cells guide.

voice_timeouts

Other top-level fields

msc.json

MSC call control and voice policy.

Top-level

base_stations

The base stations the MSC serves, one entry per BSC. The MSC dials each base station’s management endpoint to enroll it, then connects A1. See the Multiple Base Stations guide.

voice

voice.release_timeout_ms and voice.service_connect_timeout_ms moved to voice_timeouts in bsc.json.

voice.gateway

welcome_sms

sms_retry

Delivery retry settings now belong to sweep in smsc.json. Move sms_retry.enabled and sms_retry.retry_after_secs there, and rename sms_retry.sweep_interval_secs to sweep.interval_secs. The MSC’s legacy sms_retry settings no longer control the retry scan.

otasp

Over-the-air provisioning (*228). See the OTASP guide for end-to-end behavior.

otasp.home_network

otasp.system_tag

otasp.nam_defaults

Mobile-terminated call acceptance bits written into every CDMA/Analog NAM and CDMA NAM block.

otasp.mms

otasp.writes

Per-block opt-in for what *228 overwrites on the handset. Every flag defaults to false so a freshly-installed system reads each block back, shows it on the session detail page, but never changes anything.

voice-gw.json

cdma-voice-gw SIP/RTP bridge configuration. See the Voice Gateway Setup guide for end-to-end deployment instructions.

grpc

sip

rtp

nat

calls

queues

logging

Media

pdsn.json

Packet data transport configuration.

Top-level

a11_security

packet

packet.mobile_ip

Mobile IPv4 is selected only when it is enabled and the peer IPCP request omits the IP-Address option. A peer request containing IP=0.0.0.0 or another IP-Address option follows the normal Simple IP negotiation.

In insecure mode, a phone that asks for authenticated registration returns to Simple IP negotiation. In mn_ha mode, the SPI and secret must match the phone. If the request also includes MN-AAA and allow_unverified_mn_aaa is false, the PDSN tries Simple IP instead.

The checked-in pdsn.json enables mn_ha with compatibility values used by tested legacy Sprint phones. These are not secure, general-purpose credentials. Change them only when the phone is provisioned with matching values.

By default, DNS points phones at the packet gateway resolver. In the compose stack this resolves speed and speed.local.1xbts.org to the local speed test. Simple IP supplies these values through IPCP. Mobile IPv4 supplies them after a successful registration. Set primary_dns and secondary_dns to external resolvers if you do not want gateway-local DNS.

Transport modes:

• tun — kernel TUN device; packets routed via NAT on tun_nat_interface
• fou — FOU (Foo-over-UDP) tunnel; direct UDP encapsulation
• fou_tcp — FOU with TCP relay (for NAT traversal); connects to fou_remote

hlr.json

HLR subscriber database configuration.

smsc.json

SMS storage, routing, retry, and optional SMPP hub configuration. See the SMS guide for setup and testing.

sweep

smpp

Keep credentials in config/smsc.local.json. The link uses plain TCP and reconnects automatically. It is independent of the voice gateway’s SIP configuration.

management.json

BSC management endpoint configuration. This is the address the MSC enrolls the base station through (base_stations[].management_endpoint in msc.json).

mtls (optional)

events.json

Aggregated event bus configuration. The BTS, PDSN and other components publish to it through their events_endpoint, and the web dashboard subscribes to the unified stream.

pcf.json

PCF-side packet service client configuration.

a11_security

The checked-in pcf.json and pdsn.json include matching A11 credentials for local operation. Override both sides together with pcf.local.json and pdsn.local.json for a deployment-specific association.

Radio Configs

Radio config files are standalone JSON passed via --radio-config, or placed inline under radio in bts.json. The shipped profiles are radio_uhd_b210_native.json, radio_limesdr_mini2_native.json, radio_bladerf_micro2.json, radio_soapydr_example.json and radio_network.json. The mobile station and cdma-radiod take the same files with --radio.

Common Fields

TX/RX sample rates and RF bandwidths are not radio-config fields. They are derived from bts.json carrier mode at startup.

UHD (kind: "uhd")

{
  "kind": "uhd",
  "device": "type=b200,num_recv_frames=1024,num_send_frames=1024",
  "channel": 0,
  "antenna": "TX/RX",
  "tx_gain_db": 65.0,
  "master_clock_rate": 39321600,
  "clock_source": null,
  "time_source": null,
  "rx_antenna": "RX2",
  "rx_gain_db": 30.0,
  "rx_reference_dbm": null,
  "rx_power_adj": 0.0,
  "rx_sample_delay": 50,
  "traffic_rx_continuity": true,
  "rx_batch_pcgs": 2
}

LimeSDR Native (kind: "lime")

{
  "kind": "lime",
  "device": "",
  "channel": 0,
  "tx_antenna": "BAND1",
  "tx_gain_db": 80,
  "rx_antenna": "LNAW",
  "rx_gain_db": 50,
  "rx_reference_dbm": null,
  "rx_power_adj": 5.0,
  "rx_sample_delay": 97,
  "oversample": 0
}

rx_sample_delay compensates for LimeSDR hardware timing offset in the receive path. oversample is the LimeSDR oversampling ratio (0 lets the driver choose).

bladeRF Native (kind: "blade_rf")

{
  "kind": "blade_rf",
  "device": "",
  "channel": 0,
  "tx_antenna": "TXA",
  "rx_antenna": "A_BALANCED",
  "tx_gain_db": 65,
  "rx_gain_db": 20,
  "rx_reference_dbm": null,
  "rx_power_adj": 0.0,
  "rx_sample_delay": 82,
  "rx_batch_pcgs": 2,
  "num_buffers": 16,
  "buffer_size": 8192,
  "num_transfers": 8,
  "stream_timeout_ms": 3500
}

SoapySDR (kind: "soapy")

{
  "kind": "soapy",
  "device": "driver=lime",
  "channel": 0,
  "antenna": "BAND1",
  "tx_gain_db": 60.0,
  "rx_antenna": "LNAW",
  "rx_gain_db": 32.0,
  "rx_reference_dbm": null,
  "rx_power_adj": 0.0,
  "rx_sample_delay": 0,
  "rx_batch_pcgs": 2,
  "traffic_rx_continuity": true
}

Network (kind: "network")

Uses a radio served by cdma-radiod on another machine.

{
  "kind": "network",
  "addr": "radio-host:50710",
  "data_host": "radio-host",
  "samples_per_packet": 2200,
  "tx_transport": "tcp",
  "rx_enabled": true
}

Device, antenna, TX gain and stream settings stay in the radio config cdma-radiod runs with.

ms.json

Mobile station identity, channel and transmit calibration. See Mobile Station for every key.

radiod_network.json

cdma-radiod listeners. See Remote Radio.

Default Ports

Ports the handsets see on the packet-data tunnel (10.55.0.1):