API & Integration
1xBTS exposes gRPC for management, web integration, local HLR/SMSC/packet service boundaries, and the MSC-owned voice gateway client. Protocol seams with standards-defined behavior use their own transports: Abis, A1, A2p, A8/A9, and A10/A11 are not gRPC APIs.
Endpoints
| Endpoint | Default | Notes |
|---|---|---|
| Management facade / compatibility bundle | 127.0.0.1:17016 | current primary endpoint used by 1xbts-web |
| MSC management | 127.0.0.1:17017 | MSC-owned call actions, call list, and SMS submission |
| HLR service | 127.0.0.1:17019 | subscriber, identity, and registration persistence API |
| SMSC service | 127.0.0.1:17020 | SMS submission and delivery persistence API |
| Packet service | 127.0.0.1:17021 | packet sessions and packet data service API |
| Event bus | 127.0.0.1:17023 | aggregated event stream across all components |
| Voice gateway | 127.0.0.1:17015 | MSC-controlled SIP/RTP bridge gRPC control and media streams |
| 1xbts-web | http://localhost:3000 | Next.js UI and SSE bridge |
Management Services
| Proto service | Purpose |
|---|---|
management.v1.ManagementFacadeService | system overview and aggregated management event stream |
bts_management.v1.BtsManagementService | BTS status/config, radio metrics, IQ capture, local radio resources, reverse power-control state |
bsc_management.v1.BscManagementService | BSC status, mobiles, channels, access/paging/traffic streams, power override |
msc_management.v1.MscManagementService | initiate/list calls, SMS submission, MSC-owned voice policy actions |
pcf_management.v1.PcfManagementService | initiate data call and inspect PCF sessions |
pdsn_management.v1.PdsnManagementService | inspect PDSN sessions and control packet trace capture |
Compatibility services currently remain on the same endpoint for web routes and tooling: bsc.v1.BscService, hlr.v1.HlrService, smsc.v1.SmscService, and packet.v1.PacketService.
HLR, SMSC, and packet services now also run on their own local gRPC ports. The facade keeps compatibility routes on :17016, while runtime code talks to the service endpoints directly.
1xbts-web reads MANAGEMENT_GRPC_ADDRESS for the facade endpoint and falls back to the older BSC_GRPC_ADDRESS variable for compatibility. MSC-owned operations should target the MSC management endpoint or the facade route that proxies to it.
grpcurl Examples
grpcurl -plaintext localhost:17016 management.v1.ManagementFacadeService/GetSystemOverview
grpcurl -plaintext localhost:17016 bts_management.v1.BtsManagementService/StreamRadioMetrics
grpcurl -plaintext localhost:17016 bsc_management.v1.BscManagementService/ListMobiles
grpcurl -plaintext localhost:17017 msc_management.v1.MscManagementService/ListCalls
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/ListenEventsEventService
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/ListenEventsPublishing
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—PacketSessionBoundandPacketSessionUnboundcarry subscriber identity, mobile IP, service option, and the A11 session reference.PacketSessionUnboundincludes a structuredPacketSessionUnbindReasonenum.BscEvent/MscEvent/PcfEvent/HlrEvent/SmscEvent/BtsEvent— reserved per-component wrappers; variants are added as producers come online.
Compatibility examples:
grpcurl -plaintext localhost:17016 bsc.v1.BscService/GetSystemStatus
grpcurl -plaintext -d '{"destination_mdn":"5551234567","message":"test"}' \
localhost:17017 msc_management.v1.MscManagementService/SendSmsWeb Route Mapping
| Web route | Current backend | Target owner |
|---|---|---|
/api/system-status | BscService.GetSystemStatus | facade or BscManagementService |
/api/radio-metrics | BscService.StreamRadioMetrics | BtsManagementService |
/api/iq-capture | BscService.Get/Start/StopIqCapture | BtsManagementService |
/api/mobiles | BscService.ListMobiles | BscManagementService |
/api/channels | BscService.ListChannels | BscManagementService plus BTS resource state |
/api/calls | MscManagementService.InitiateCall / ListCalls | MscManagementService |
/api/data-call | BscService.InitiateDataCall | PcfManagementService |
/api/packet-sessions | PacketService.ListSessions via facade or :17021 | PcfManagementService / PdsnManagementService |
/api/subscribers | HlrService via facade or :17019 | HLR management target |
/api/sms-history | SmscService via facade or :17020 | SMSC management target |
Browser clients should keep using 1xbts-web routes. Backend service ownership can move without changing the browser-facing route URLs.