API & Integration

1xBTS uses gRPC for management, for the web dashboard, and for the service boundaries between components (HLR, SMSC, packet core, event bus, voice gateway). Standards interfaces keep their own transports: Abis, A1, A2p, A8/A9, and A10/A11 are not gRPC APIs.

Management service diagram

Endpoints

Endpoint	Default	Hosted by	Notes
Network management	`127.0.0.1:17017`	MSC	The one endpoint the web dashboard and operator tooling call. Calls, SMS, OTASP, and every radio, HRPD and packet view for every base station.
Base station management	`127.0.0.1:17016`	BSC	Enrollment plus per-base-station management. The MSC calls it; the web does not.
Cell management	`127.0.0.1:17024`	BTS	Enrollment plus radio metrics, IQ capture, and reverse power control for one cell. The BSC calls it.
HRPD access network	`127.0.0.1:17030`	BTS	HRPD sessions and UATI allocation for one EV-DO cell. The MSC calls it.
HLR service	`127.0.0.1:17019`	HLR	Subscribers, identities, registrations, PRLs, OTASP sessions
SMSC service	`127.0.0.1:17020`	SMSC	SMS submissions and delivery attempts
Packet service	`127.0.0.1:17021`	PDSN	Packet sessions
Event bus	`127.0.0.1:17023`	Event bus	Aggregated event stream across all components
Voice gateway	`127.0.0.1:17015`	Voice gateway	MSC-controlled SIP/RTP bridge control and media streams
1xbts-web	`http://localhost:3000`	Web dashboard	Next.js UI and SSE bridge

Services

Proto service	Hosted by	Purpose
`mgmt.v1.NetworkManagementService`	MSC	Single management interface for the whole network. Each call names a base station (and, where relevant, a cell) and the MSC forwards it there, or fans out to every base station for network-wide views.
`msc_management.v1.MscManagementService`	MSC	List base stations, initiate and list calls, send SMS, stream OTASP events
`base_station.v1.BaseStationService`	BSC	Enrollment: reports the base station’s identity, A1 address and served cells to the MSC
`bsc_management.v1.BscManagementService`	BSC	BSC status, mobiles, channels, access/paging/traffic event streams, power override
`bts_management.v1.BtsManagementService`	BTS, and per cell on the BSC	Cell enrollment, status and config, radio metrics, IQ capture, reverse power control
`an.v1.AnService`	BTS	HRPD sessions, UATI allocation and session events for one EV-DO cell
`hlr.v1.HlrService`	HLR	Subscriber, identity, registration, PRL and OTASP session persistence
`smsc.v1.SmscService`	SMSC	SMS submission and delivery persistence
`packet.v1.PacketService`	PDSN	Packet session lifecycle and inspection
`events.v1.EventService`	Event bus	Aggregated network events
`voice_gateway.v1.VoiceGateway`	Voice gateway	Call control and media streams driven by the MSC

StreamRadioMetrics includes TX hardware-margin and late-batch counters, radio underflow/late/sequence status, real-time scheduling degradation counts, and RX queue depth, queued airtime, and maximum residency. These fields help distinguish an overloaded host from an RF or handset-side problem.

Web dashboard

1xbts-web reads four addresses, all set in docker-compose.yml:

Variable	Default	Used for
`MSC_GRPC_ADDRESS`	`127.0.0.1:17017`	All management: base stations, cells, mobiles, channels, calls, SMS, OTASP, HRPD sessions, packet sessions
`HLR_GRPC_ADDRESS`	MSC host, port `17019`	Subscribers and PRLs
`SMSC_GRPC_ADDRESS`	MSC host, port `17020`	SMS history
`EVENTS_GRPC_ADDRESS`	`127.0.0.1:17023`	Live event stream

The web never connects to a BSC, a BTS, the HRPD access network, or the PDSN directly. Browser clients talk to the web’s own API routes and receive SSE streams from it, and they do not open gRPC connections.

grpcurl Examples

grpcurl -plaintext localhost:17017 msc_management.v1.MscManagementService/ListBaseStations
grpcurl -plaintext localhost:17017 msc_management.v1.MscManagementService/ListCalls
grpcurl -plaintext -d '{"destination_mdn":"5551234567","message":"test"}' \
  localhost:17017 msc_management.v1.MscManagementService/SendSms
grpcurl -plaintext localhost:17017 mgmt.v1.NetworkManagementService/ListAllMobiles
grpcurl -plaintext localhost:17019 hlr.v1.HlrService/ListSubscribers
grpcurl -plaintext localhost:17020 smsc.v1.SmscService/ListSmsSubmissions
grpcurl -plaintext localhost:17021 packet.v1.PacketService/ListSessions
grpcurl -plaintext -d '{}' localhost:17023 events.v1.EventService/ListenEvents

Per-base-station calls on NetworkManagementService take a selector naming the base station id from msc.json (and a cell id where the call is cell-scoped):

grpcurl -plaintext -d '{"selector":{"base_station":"bts-1"}}' \
  localhost:17017 mgmt.v1.NetworkManagementService/ListMobiles

EventService

events.v1.EventService is the aggregated network event bus. Subscribe to ListenEvents to receive a long-lived stream of NetworkEvent messages from every component in the stack.

Envelope

Field	Description
`timestamp`	Server-assigned event time
`source`	`EventSource` enum — `BTS`, `BSC`, `MSC`, `PCF`, `PDSN`, `HLR`, `SMSC`, `NIB`
`sequence`	Monotonically increasing per-server sequence number
`producer_instance`	Free-form producer label (e.g. `"pdsn-0"`)
`body`	`oneof` over per-component wrapper messages (`PdsnEvent`, `BscEvent`, …)

Subscribing

# All events
grpcurl -plaintext -d '{}' localhost:17023 events.v1.EventService/ListenEvents

# Only PDSN events
grpcurl -plaintext -d '{"source_filter":["EVENT_SOURCE_PDSN"]}' \
  localhost:17023 events.v1.EventService/ListenEvents

Publishing

Components publish events to the bus via the unary Publish RPC. Producers hold one long-lived gRPC channel and rely on HTTP/2 multiplexing for cheap per-event calls. Each Publish returns the server-assigned sequence number.

Per-component bodies

PdsnEvent — PacketSessionBound and PacketSessionUnbound carry subscriber identity, mobile IP, service option, and the A11 session reference. PacketSessionUnbound includes a structured PacketSessionUnbindReason enum.
BscEvent / MscEvent / PcfEvent / HlrEvent / SmscEvent / BtsEvent — per-component wrappers. Variants are added as producers come online.