CAMEL Gateway Configuration Guide

Overview

The CAMEL Gateway (CAMELGW) mode turns OmniSS7 into an Intelligent Network (IN) platform that provides real-time call control and charging using the CAMEL Application Part (CAP) protocol. OmniSS7 acts as the gsmSCF (Service Control Function), receiving triggers from the gsmSSF in the MSC/VLR/GMSC and driving charging decisions through CGrateS.

CAMEL Request Builder Overview

What is CAMEL?

CAMEL (Customized Applications for Mobile network Enhanced Logic) is a set of standards that work on either a GSM core network or a UMTS network. It lets operators provide services that require real-time control of calls, such as:

Prepaid calling - Real-time balance checking and charging
Premium rate services - Special billing for value-added services
Call routing control - Dynamic destination routing based on time/location
Virtual private networks - Corporate numbering plans
Call screening - Allow/block calls based on criteria

CAP Protocol Versions

OmniSS7 CAMELGW supports multiple CAP versions. The version controls the application-context OID carried in the TCAP dialogue:

Version	Phase	Application-Context OID
CAP v1	CAMEL Phase 1	`0.4.0.0.1.0.50.0`
CAP v2	CAMEL Phase 2	`0.4.0.0.1.0.50.1`
CAP v3	CAMEL Phase 3	`0.4.0.0.1.21.3.4`
CAP v4	CAMEL Phase 4	`0.4.0.0.1.23.3.4`

Default: CAP v2 (most widely deployed). The incoming version is auto-detected from the InitialDP dialogue portion and reused when generating the response, so responses match each MSC's CAP version.

Architecture

Call Flow Example

Configuration

Prerequisites

OmniSS7 installed and running
M3UA connectivity to MSC/GMSC (gsmSSF)
A CGrateS instance reachable over JSON-RPC (optional, for real-time charging)

Enable CAMEL Gateway Mode

CAMEL processing is controlled by two independent flags. cap_client_enabled brings up the CAP/M3UA client and CAMEL session components; cgrates_enabled turns on the CGrateS charging integration behind the backend. Configure these in config/runtime.exs:

config :omniss7,
  # Bring up the CAP/CAMEL client (M3UA ASP, SessionStore, request handling)
  cap_client_enabled: true,

  # Other independent modes (set as needed for your deployment)
  map_client_enabled: false,
  smsc_mode_enabled: false,

  # CAP version used for outgoing requests / dialogue (:v1 | :v2 | :v3 | :v4)
  cap_version: :v2,

  # CGrateS charging integration
  cgrates_enabled: true,

  # M3UA connection for CAP (connect as ASP toward the MSC/GMSC gsmSSF)
  cap_client_m3ua: %{
    routing_context: 1,
    opc: 5013,
    dpc: 5011
  }

Note on cap_client_m3ua: the CAMEL client reads only :routing_context, :opc, and :dpc from this map. Any additional keys are ignored by the CAP client. The M3UA ASP process name is fixed internally as :camelgw_client_asp.

There is no camelgw_mode_enabled, hlr_mode_enabled, or smsc_mode_enabled-for-CAMEL flag. The only flags that gate CAMEL behaviour are cap_client_enabled and cgrates_enabled.

Mode Flags

Key	Default	Purpose
`cap_client_enabled`	`false`	Starts the CAP/CAMEL client (M3UA ASP, SessionStore, CAP request handling)
`cgrates_enabled`	`false`	Enables CGrateS charging integration in `CAMELGW.Backend`
`cap_version`	`:v2`	Default CAP version / dialogue OID for outgoing requests
`map_client_enabled`	`false`	Independent MAP client mode
`smsc_mode_enabled`	`false`	Independent SMSc mode (requires MAP client)

CGrateS Charging Parameters

Key	Default	Purpose
`cgrates_enabled`	`false`	Master switch for CGrateS integration
`cgrates_url`	`http://localhost:2080/jsonrpc`	CGrateS JSON-RPC endpoint
`cgrates_tenant`	`cgrates.org`	Tenant used on every SessionS event
`cgrates_request_type`	`*prepaid`	CGrateS request type (e.g. `prepaid`, `postpaid`)
`cgrates_timeout`	`5000`	HTTP request timeout in milliseconds

Configure Web UI Pages

The Web UI exposes the CAMEL pages through the control panel. These are configured in config/config.exs:

config :control_panel,
  use_additional_pages: [
    {SS7.Web.EventsLive, "/events", "SS7 Events"},
    {SS7.Web.M3UAStatusLive, "/m3ua", "Peers"},
    {SS7.Web.CAMELSessionsLive, "/camel_sessions", "CAMEL Sessions"},
    {SS7.Web.CAMELRequestLive, "/camel_request", "CAMEL Request Builder"}
  ],
  page_order: [
    "/events", "/m3ua", "/camel_sessions", "/camel_request",
    "/application", "/configuration"
  ]

Page label	Route	Module
Peers	`/m3ua`	`SS7.Web.M3UAStatusLive`
CAMEL Sessions	`/camel_sessions`	`SS7.Web.CAMELSessionsLive`
CAMEL Request Builder	`/camel_request`	`SS7.Web.CAMELRequestLive`

CAP Operations Supported

CAP operations are identified by name and direction. Note that the codebase is internally inconsistent on some CAP opcode numbers (the event-log opcode map and the request generator disagree on a few operations), so operations below are described by name and endpoint. Where an opcode is cited, it is the one cap_request_generator.ex actually emits.

Incoming Operations (gsmSSF → gsmSCF)

Handled in cap_request.ex (handle_request/1 dispatch on the decoded TCAP component opcode):

Operation	Handler	Notes
InitialDP	`handle_initial_dp/1`	Call setup notification; triggers CGrateS `InitiateSession`. Accepted at opcode 0, and also at opcode 60 (treated as InitialDP/InitialDPSMS)
AssistRequestInstructions	`handle_assist_request_instructions/1`	Acknowledged; dispatched at opcode 1 in a TCAP Begin
EventReportBCSM	`handle_event_report_bcsm/1`	BCSM events (oAnswer, oDisconnect, …); drives CGrateS update/terminate
Continue	`handle_continue/1`	Acknowledged
ConnectToResource	`handle_connect_to_resource/1`	Acknowledged
RequestReportBCSMEvent	`handle_request_report_bcsm_event/1`	Acknowledged
ApplyCharging	`handle_apply_charging/1`	Parameters BER-decoded and acknowledged
Connect	`handle_connect/1`	Parameters BER-decoded and acknowledged
ReleaseCall	`handle_release_call/1`	Acknowledged

Unhandled opcodes are answered with a TCAP error (Facility Not Supported / Unexpected Data Value).

Outgoing Operations (gsmSCF → gsmSSF)

Generated by cap_request_generator.ex and sent via CapClient. The opcodes below are the values the generator emits:

Operation	Opcode	Generator	Sender
InitialDP	0	`CapRequestGenerator.initial_dp_request/3`	`CapClient.initial_dp/3`
Connect	20	`CapRequestGenerator.connect_request/2`	`CapClient.connect/3`
ReleaseCall	22	`CapRequestGenerator.release_call_request/2`	`CapClient.release_call/3`
RequestReportBCSMEvent	23	`CapRequestGenerator.request_report_bcsm_event_request/2`	—
Continue	31	`CapRequestGenerator.continue_request/1`	`CapClient.continue/2`
ApplyCharging	35	`CapRequestGenerator.apply_charging_request/3`	`CapClient.apply_charging/4`
InitialDPSMS	60	`CapRequestGenerator.initial_dp_sms_request/5`	—
NoteMM-Event	89 (MAP)	`CapRequestGenerator.note_mm_event_request/4`	—

InitialDPSMS (opcode 60) is for MO-SMS CAMEL control: sent by the smsSSF to the gsmSCF when an SMS-CSI / mo-sms-CSI is armed, before the short message is relayed to the SMSC. The arg is encoded with the generated CAP ASN.1 module and the dialogue carries the id-ac-cap3-sms-AC application context.

NoteMM-Event is a MAP operation (opcode 89, not CAP) used for CAMEL M-CSI mobility notifications from the VLR to the gsmSCF. It is encoded with the MAP ASN.1 module (:TCAPMessages.encode(:MapSpecificPDUs, …)) and carries the mm-EventReporting-v3 application context.

All CAP TCAP messages are encoded with :GenericTCAP.encode(:GenericPDUs, …). Only the MAP-based NoteMM-Event uses :TCAPMessages.

Web UI Features

CAMEL Sessions Page

Title: CAMEL Sessions · Route: /camel_sessions (HTTPS, port 8087)

Real-time monitoring of active CAMEL call sessions:

Live session list with auto-refresh
Session details - OTID, Call ID, State, Duration
CAP Version detected from InitialDP and stored per session
Call information - IMSI, A-number, B-number, Service Key
State tracking - initiated, answered, terminated

Table Columns: Call ID, State, Version, IMSI, Calling Number, Called Number, Service Key, Duration, Start Time, OTID

The same session data is available over the REST API at /camel-sessions (see Monitoring & Operations).

CAMEL Request Builder

Title: CAMEL Request Builder · Route: /camel_request (HTTPS, port 8087)

Interactive tool for building and sending CAP requests for testing. See the dedicated CAMEL Request Builder Guide for full details.

Request types offered by the form: InitialDP, Connect, ReleaseCall, RequestReportBCSMEvent, ApplyCharging, Continue.

CAP version selector: the form has a per-request CAP version dropdown (v1/v2/v3/v4 with their OIDs). The selection temporarily overrides the configured default for that request and persists across form changes; the request history shows the version used in a CAP Ver column.

Advanced SCCP/M3UA options:

Field	Default	Notes
Called Party GT	`68988415011`	Destination Global Title
Calling Party GT	(configurable)	Originating Global Title
Called SSN	`146`	gsmSSF
Calling SSN	`146`	gsmSSF
OPC	`5013`	Originating Point Code
DPC	`5011`	Destination Point Code

Integration with CGrateS

OmniSS7 charges calls through the CGrateS SessionS JSON-RPC API. CGrateS.SessionsClient posts to the configured cgrates_url and maps CAP operations to SessionS methods:

CAP trigger	SessionS method
InitialDP	`SessionSv1.InitiateSession`
EventReportBCSM (oAnswer)	`SessionSv1.UpdateSession`
EventReportBCSM (oDisconnect)	`SessionSv1.TerminateSession`

Call Lifecycle with Charging

1. Call Initiation (InitialDP)

When the MSC sends InitialDP, CAMELGW:

Detects the CAP version from the dialogue portion (falls back to the configured default)
Decodes the InitialDP parameters (IMSI, calling/called numbers, service key)
Calls CGrateS SessionSv1.InitiateSession via CAMELGW.Backend.handle_initial_dp/1
Reads MaxUsage from the response (allowed call duration in seconds)
Stores the session in CAMELGW.SessionStore (ETS) keyed by OTID, including the CAP version and a call ID of the form CAMEL-<hex OTID>
Responds to the MSC using the detected CAP version

The account on the SessionS event is the subscriber IMSI when present, otherwise the calling number. The event also carries Destination, ServiceKey, MSCAddress, CallingPartyNumber, CalledPartyNumber, and OriginID (the call ID).

2. Call Answer (EventReportBCSM - oAnswer)

On oAnswer, the backend looks up the session, sets its state to answered, and calls SessionSv1.UpdateSession with usage 0 to start the debit loop. If CGrateS fails, the call is not dropped — the backend logs the error and continues.

3. Call Termination (EventReportBCSM - oDisconnect)

On oDisconnect, the backend computes the total duration from the session start time, sets state to terminated, calls SessionSv1.TerminateSession with the final usage, and deletes the session from the store. CDRs are generated by CGrateS. The session is cleaned up even if the terminate call errors.

CDR Fields from CAMEL

CDRs are produced by CGrateS and typically include:

Account - IMSI (or calling number fallback)
Destination - Called party number
OriginID - Call identifier (CAMEL-<hex OTID>)
Usage - Total call duration (seconds)
IMSI, CallingPartyNumber, CalledPartyNumber
MSCAddress - Serving MSC
ServiceKey - CAMEL service key

Testing

Manual Testing with the Request Builder

Open https://your-server:8087/camel_request
Select InitialDP, set Service Key / Calling / Called numbers, optionally pick a CAP version, and send. Note the OTID generated.
Open https://your-server:8087/camel_sessions to see the session in state initiated.
Send EventReportBCSM with oAnswer to move the session to answered.
Send ReleaseCall with cause 16 (Normal) to terminate.

Testing with a Real MSC

Configure CAMEL service on your MSC/VLR (Service Key, gsmSCF Global Title) so it triggers InitialDP toward OmniSS7. Example for a Huawei MSC:

ADD CAMELSERVICE:
  SERVICEID=1,
  SERVICEKEY=100,
  GSMSCFADDR="55512341234",   # CAMELGW Global Title
  DEFAULTCALLHANDLING=CONTINUE;

ADD CAMELSUBSCRIBER:
  IMSI="310150123456789",
  SERVICEID=1,
  TRIGGERTYPE=TERMCALL;

Monitor Logs

OmniSS7 emits structured JSON logs (one object per line via OmniLogger.JsonFormatter), so you can filter on metadata fields:

# Tail and filter CAP events by the map_event field
tail -f /var/log/omniss7/omniss7.log | jq 'select(.map_event | tostring | startswith("CAP:"))'

Monitoring & Operations

Prometheus Metrics

CAMELGW exposes metrics at http://localhost:8080/metrics.

CAP metrics:

cap_requests_total{operation} - Total CAP requests by operation. Label values are snake_case, e.g. initial_dp, connect, release_call, continue, apply_charging.
cap_request_errors_total{operation} - CAP request generation/send errors by operation.

MAP / API metrics:

map_requests_total{operation} - Total MAP requests by operation
map_pending_requests - Number of pending MAP TID waiters

M3UA STP metrics (if STP mode enabled):

m3ua_stp_routing_failures_total{reason} - Routing failures by reason

# All CAP request counters
curl http://localhost:8080/metrics | grep cap_requests_total

# InitialDP only (note snake_case label)
curl http://localhost:8080/metrics | grep 'cap_requests_total{operation="initial_dp"}'

Health Checks

# M3UA peer status (TLS API on port 8445)
curl -k https://localhost:8445/m3ua-status

# Active CAMEL sessions (returns session_count + per-session detail)
curl -k https://localhost:8445/camel-sessions

There is no /api/ocs-status, /api/events, or /api/camel/sessions/count endpoint. Session counts come from /camel-sessions.

Logging Configuration

Adjust the log level in config/runtime.exs:

config :logger, level: :info   # :debug | :info | :warning | :error

The formatter is set to structured JSON in config/config.exs:

config :logger, :default_formatter,
  format: {OmniLogger.JsonFormatter, :format},
  metadata: :all,
  truncate: :infinity

Troubleshooting

Issue: No CAP messages received

Symptoms: Request Builder works, but the MSC never sends InitialDP.

Check:

M3UA peer status: curl -k https://localhost:8445/m3ua-status
MSC CAMEL service configuration (Service Key, gsmSCF address)
SCCP routing (the gsmSCF Global Title must route to CAMELGW)
Firewall rules (allow SCTP port 2905)

Issue: CGrateS errors

Symptoms: not_configured, http_error, or cgrates_error in logs.

Check:

cgrates_enabled: true and cgrates_url point at a reachable JSON-RPC endpoint
The account (IMSI or calling number) exists and has balance in CGrateS
cgrates_tenant and cgrates_request_type match your CGrateS rating setup
cgrates_timeout is large enough for your CGrateS latency

On a charging failure during a call, CAMELGW continues the call rather than dropping it; the error is logged.

Issue: Session not found

Symptoms: EventReportBCSM logs "Session not found".

Cause: OTID mismatch or the session was already terminated.

Check: Verify the OTID in logs and ensure the DTID/OTID correlate across the dialogue.

Issue: Decode errors

Symptoms: "Failed to decode InitialDP" in logs.

Cause: CAP version mismatch or malformed message.

Check: Confirm the CAP version configuration matches the MSC, and capture a PCAP for analysis:

tcpdump -i eth0 -w cap_trace.pcap sctp port 2905

Summary

The CAMEL Gateway mode enables OmniSS7 to act as a gsmSCF with:

CAP protocol support (v1/v2/v3/v4) with per-request version override
Real-time charging via the CGrateS SessionS JSON-RPC API
Call control operations (Connect, Release, Continue, ApplyCharging)
Session management in ETS, keyed by OTID
Interactive testing via the Web UI Request Builder
Live monitoring of active sessions (Web UI and /camel-sessions API)
CDR generation by CGrateS for billing and analytics

For more detail:

Product: OmniSS7 CAMEL Gateway Documentation Version: 1.1

Overview​

What is CAMEL?​

CAP Protocol Versions​

Architecture​

Call Flow Example​

Configuration​

Prerequisites​

Enable CAMEL Gateway Mode​

Mode Flags​

CGrateS Charging Parameters​

Configure Web UI Pages​

CAP Operations Supported​

Incoming Operations (gsmSSF → gsmSCF)​

Outgoing Operations (gsmSCF → gsmSSF)​

Web UI Features​

CAMEL Sessions Page​

CAMEL Request Builder​

Integration with CGrateS​

Call Lifecycle with Charging​

1. Call Initiation (InitialDP)​

2. Call Answer (EventReportBCSM - oAnswer)​

3. Call Termination (EventReportBCSM - oDisconnect)​

CDR Fields from CAMEL​

Testing​

Manual Testing with the Request Builder​

Testing with a Real MSC​

Monitor Logs​

Monitoring & Operations​

Prometheus Metrics​

Health Checks​

Logging Configuration​

Troubleshooting​

Issue: No CAP messages received​

Issue: CGrateS errors​

Issue: Session not found​

Issue: Decode errors​

Summary​