Configuration Reference

Run the integrated runtime with a config directory:

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

Runtime Flags

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).

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.

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. When enabled in the integrated runtime, cdma-nib starts the HRPD AN service, PCF A9 signaling, and PDSN A11 signaling, then bridges decoded HRPD air events between the BTS PHY and AN session layers.

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 via the iana-time-zone crate. 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.

runtime.uplink

Reverse link configuration.

runtime.overhead

Overhead channel scheduling.

abis

Abis TCP signaling address (BTS side).

bearer

Abis UDP bearer addressing (BTS side).

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

abis_timers

BSC-side Abis timers per A.S0003-A §8 Table 8-1. Granularity is 100 ms; ranges are 0–1000 ms except tsetupb_ms (0–500).

abis

Abis TCP signaling address (BSC side).

bearer

Abis UDP bearer addressing (BSC side).

Other top-level fields

msc.json

MSC call control and voice policy.

Top-level

voice

voice.gateway

welcome_sms

otasp

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

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

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

SMSC message store configuration.

management.json

Management gRPC facade configuration.

mtls (optional)

events.json

Aggregated event bus configuration. When this file is present, cdma-nib starts the events.v1.EventService gRPC service. Producers (e.g. PDSN via pdsn.json’s events_endpoint) publish to it; subscribers consume the unified stream via ListenEvents.

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. They are independent of the config/ directory.

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,
  "rx_antenna": "RX2",
  "rx_gain_db": 30.0,
  "rx_power_adj": 0.0,
  "rx_sample_delay": 50
}

LimeSDR Native (kind: "lime")

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

rx_sample_delay compensates for LimeSDR hardware timing offset in the receive path.

bladeRF Native (kind: "blade_rf")

{
  "kind": "blade_rf",
  "device": "",
  "channel": 0,
  "tx_antenna": "TXA",
  "rx_antenna": "A_BALANCED",
  "tx_gain_db": 60,
  "rx_gain_db": 35,
  "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": "",
  "channel": 0,
  "antenna": "TX/RX",
  "tx_gain_db": 60.0,
  "rx_antenna": "RX2",
  "rx_gain_db": 50.0,
  "rx_sample_delay": 0,
  "rx_batch_pcgs": 2
}

Default Ports