dvmhost/tools/callsim/README.md

callsim

callsim is a command-line FNE peer that generates deterministic group voice calls for exercising DMR, P25, and NXDN call handling. It authenticates to an FNE traffic port as one peer and can emit calls sequentially or multiplex simultaneous calls to several talkgroups over that single connection.

The generated audio is a fixed calibration-tone test pattern. P25 uses the project's 1011 Hz IMBE vector, while DMR uses its 1031 Hz AMBE vector. NXDN builds its voice payload from the fixed AMBE test bits and applies the NXDN voice encoding and interleaving used by the common library. This is synthetic protocol traffic; the tool does not read audio from a file or sound device.

Build

Build the target from a configured repository build tree:

cmake --build build --target callsim -j6

Depending on whether dvmhost is built directly or as part of the superproject, the executable will normally be build/callsim or build/dvmhost/callsim.

Basic usage

The protocol mode and at least one destination talkgroup are required:

build/callsim \
    --address 127.0.0.1 \
    --port 62031 \
    --peer-id 9000998 \
    --password passw0rd \
    --mode p25 \
    --talkgroups 1001 \
    --calls 3 \
    --duration 5

This example logs in as peer 9000998 and sends three five-second P25 Phase 1 group calls to talkgroup 1001. Source radio IDs begin at 100001 and increase by one for every generated call.

Options

Option	Description
--address <host>	FNE address. The default is 127.0.0.1.
--port <port>	FNE UDP traffic port. The default is 62031.
--peer-id <id>	Peer ID used for FNE authentication. The default is 9000998.
--password <password>	FNE peer password. The default is passw0rd.
--identity <name>	Peer identity reported to the FNE. The default is CallSim.
--mode <mode>	Required digital mode: p25, dmr, or nxdn.
--talkgroups <list>	Required comma-separated destination talkgroup IDs.
--calls <count>	Number of calls, or simultaneous-call batches. The default is 1.
--duration <seconds>	Duration of each call in seconds. The default is 5.
--gap <ms>	Delay between calls or batches in milliseconds. The default is 500.
--source <rid>	Source radio ID for the first call. The default is 100001.
--slots <list>	Comma-separated DMR slots (1 or 2), cycled as needed. The default is slot 1.
--grant-demand	Sends an FNE group-call grant request before every call.
--simultaneous	Starts one call per configured talkgroup in each batch.
--debug	Enables verbose network logging.
--help, -h	Displays command-line help.

P25 and DMR source and destination IDs may be up to 24 bits. NXDN source and destination IDs must not exceed 65535. The --slots setting is used only for DMR; P25 and NXDN are FDMA modes.

Multiple talkgroups

Without --simultaneous, calls are sent one at a time and the talkgroup and DMR slot lists are selected round-robin:

build/callsim \
    --mode dmr \
    --talkgroups 1001,1002 \
    --slots 1,2 \
    --calls 6 \
    --duration 10

This produces six sequential calls, alternating talkgroups 1001 and 1002 and slots 1 and 2.

With --simultaneous, each repetition starts one call for every talkgroup:

build/callsim \
    --mode dmr \
    --talkgroups 1001,1002 \
    --slots 1,2 \
    --calls 3 \
    --duration 10 \
    --grant-demand \
    --simultaneous

This produces three batches of two concurrent calls. Each call has independent RTP stream and sequence state, but all traffic uses one authenticated FNE peer connection. The gap is applied between completed batches, not between members of a batch. If fewer slots than talkgroups are supplied, the slot list cycles; concurrent calls assigned to the same DMR slot may be rejected or contend under the connected FNE's policy.

Grant requests and call termination

By default, voice traffic begins without a preceding grant request. Add --grant-demand when the target system should receive an FNE group-call grant request before each voice stream. The request uses the call's source ID, talkgroup, and DMR slot where applicable.

The simulator sends normal protocol-specific call termination signalling after the requested duration: a TDU for P25, a terminator-with-link-control burst for DMR, or an RTCH transmission release for NXDN. SIGINT and SIGTERM request an orderly shutdown.

The peer ID and credentials must be accepted by the target FNE, and the selected source IDs, talkgroups, modes, and slots remain subject to its access and grant policy. Use the simulator only against a test system where generated call traffic is expected.