Teltonika

Introduction

Teltonika IoT routers serve as the connectivity backbone for GCXONE Tower Monitoring, providing real-time cellular status, GPS tracking, I/O state changes, and signal quality data from remote tower sites. This guide walks through the complete onboarding process for a Teltonika IoT router — from adding the device in GCXONE and entering the required credentials, to configuring alarm rules for network loss, geo-fencing, SIM data usage, and jammer detection.

What Teltonika Devices Monitor

Once connected to GCXONE, Teltonika routers continuously report the following categories of telemetry:

• Network connectivity status and signal quality (RSRQ, RSRP)
• SIM card data usage against configured monthly limits
• Physical input/output (I/O) port state changes — digital, analog, isolated, relay
• GPS position relative to the assigned site boundary (geo-fencing)
• Jammer detection based on sudden signal degradation patterns

Note: Teltonika handles communication, GPS tracking, and edge telemetry routing for the tower. This makes it the backbone of connectivity monitoring — without it, GCXONE cannot detect network outages, signal interference, or unauthorized device movement.

Prerequisites

Before starting device onboarding, ensure the following information and access are available:

Important: Ensure the Teltonika router is online, reachable from the GCXONE server (direct IP or via VPN), and that the administrative credentials provided have full API access.

Teltonika Config Guide with GCXONE

Follow these steps to add a Teltonika IoT router to GCXONE. The device will be registered under an existing site and begin reporting telemetry immediately after configuration.

Step 1: Navigate to the Site

In GCXONE, navigate to the Site where the Teltonika device is physically installed. This is the parent entity under which the device will be registered.

• Go to Configuration → Sites
• Locate and open the target site
• Click Edit to open the site's configuration panel

Step 2: Open the Device Dialog

Within the site configuration, navigate to the Devices section and click Add New to open the device creation dialog.

Step 3: Select Device Type

In the device dialog, open the Device Type dropdown and select Teltonika-IOT to load the appropriate configuration fields.

Step 4: Enter Device Details

Fill in all required fields to establish a secure connection between GCXONE and the Teltonika router. Each field is described in detail below.

Step 5: Below the connection fields, the dialog also has a Select Entity Group dropdown, an Enable Audio toggle (on by default), a required Timezone, a Device Configuration section (Site Pulse Configuration), an Advanced Settings section (Event Polling, Configure Heatmap Mask, Periodic Health Check, Event Retention Time — 30 days by default), and an optional Location section (Latitude, Longitude, Plus Code, What3Words).

Step 6: Save and Verify Connection

After entering all fields, click Save. GCXONE will immediately attempt to establish a connection with the Teltonika router using the provided credentials.

A successful connection results in:

• The device appearing in the site's device list with an active status indicator
• Live telemetry data beginning to flow into GCXONE (signal strength, network status, I/O states)
• The device becoming available for alarm rule configuration

Important: If the connection fails, verify that the IP address is reachable, the port is open, and the credentials are correct. Check that no firewall rules are blocking GCXONE's access to the device.

Alarm Rules Configuration

GCXONE uses a JSON-based alarm rule configuration to define which telemetry parameters are monitored, what thresholds trigger alerts, and how those alerts are identified in CMS integrations.

Alarm rules can be configured at the Site level or Device level. Teltonika connectivity rules are typically applied at the Device level for precision control.

How to Apply Alarm Rules

1. Navigate to the target Site or Device in GCXONE.
2. Click Edit and go to the Additional Properties section.
3. Locate the property named Custom Alarm Rules.
4. Open the property's three dots (⋮) and select Apply Default to load the preconfigured rule set. All rules are inactive by default.
5. Modify the JSON to enable specific rules by setting "active": true for the relevant parameters.
6. Set your thresholds, event codes, and group codes as needed.
7. Click Save. GCXONE will immediately begin evaluating incoming telemetry against the configured rules.

Tip: By default, all alarm rules are inactive. You must explicitly set "active": true for each rule you want GCXONE to monitor. This prevents accidental alerts during initial setup.

Rule Structure

Each alarm rule follows a consistent JSON structure. Understanding the common fields helps when customizing rules:

Note: Event Codes are used for cross-system CMS notification (e.g. IMMIX, Evalink). Group Codes are GCXONE-internal identifiers for tower alarm workflows. Both must be present for full integration.

Teltonika Connectivity Alarm Rules

The following alarm rules are available for Teltonika IoT devices under the Connectivity Monitoring section of the Custom Alarm Rules JSON. Each rule monitors a specific aspect of network health, physical I/O, or security.

Rule 1: Input/Output Status Change

Monitors physical state changes on Teltonika I/O ports. This rule covers digital, analog, isolated, and relay inputs and outputs — essential for detecting door openings, power events, external sensor triggers, and equipment state changes.

Default JSON Configuration

"IOStatusChange": {
  "input": {
    "AnalogCurrentLoop": {"active": false, "low": 4, "high": 20},
    "AnalogInput": {"active": false, "low": 11, "high": 14},
    "DigitalInput": {"active": false, "ranges": ["Low level", "High level"], "alertOn": "High Level"},
    "IsolatedInput": {"active": false, "ranges": ["Low level", "High level"], "alertOn": "High Level"},
    "PowerSocketInput": {"active": false, "ranges": ["Low level", "High level"], "alertOn": "High Level"},
    "eventCode": "input.statechange",
    "groupCode": "tower.input.statechange"
  },
  "output": {
    "IsolatedOutput": {"active": false, "ranges": ["Low level", "High level"], "alertOn": "High Level"},
    "Relay": {"active": false, "ranges": ["open", "closed"], "alertOn": "open"},
    "PowerSocketOutput": {"active": false, "ranges": ["Low level", "High level"], "alertOn": "High Level"},
    "eventCode": "output.statechange",
    "groupCode": "tower.output.statechange"
  }
}

Input Types

Output Types

Rule 2: SIM Card Data Package Usage

Tracks monthly mobile data consumption for the Teltonika router's SIM card. Triggers a warning when data usage reaches the configured percentage of the total monthly allowance — preventing unexpected overage charges or service interruptions.

Default JSON Configuration

"simCardDataPackage": {
  "active": false,
  "simBillingStartDate": 1,
  "simDataPackageGB": 10,
  "usageWarningPercent": 80,
  "eventCode": "sim.data.usage.warning",
  "groupCode": "tower.connectivity.simdata.alert"
}

Configuration Parameters

Example Behavior

• With simDataPackageGB set to 10 and usageWarningPercent set to 80, GCXONE triggers an alert when cumulative SIM data usage exceeds 8GB in the billing period.
• The alert clears automatically when data usage resets at the start of the new billing cycle.
• Adjust the threshold lower (e.g., 70%) for early warning on sites with limited connectivity alternatives.

Rule 3: Cellular Network Loss

Detects when the Teltonika router loses mobile network connectivity or the signal drops to an unacceptable level. Immediately alerts operators to potential site communication failures.

Default JSON Configuration

"cellNetworkLoss": {
  "active": false,
  "eventCode": "modem.signal.warning",
  "groupCode": "tower.connectivity.signal.alert"
}

Example Behavior

• GCXONE triggers an alert when the cellular signal drops below the acceptable threshold or connectivity is lost entirely.
• The alert automatically clears once the signal returns to an acceptable level.
• This rule has no threshold parameters — it relies on GCXONE's built-in signal quality evaluation for the router's reported modem status.

Rule 4: Geo-Fencing

Monitors the GPS position of the Teltonika router relative to its assigned site location. Triggers an alert if the device moves beyond the configured radius — detecting potential tower displacement, theft, or unauthorized movement.

Default JSON Configuration

"geoFencing": {
  "active": false,
  "radiusMetersWarning": 500,
  "eventCode": "geo.fence.breach",
  "groupCode": "tower.connectivity.geofence.alert"
}

Example Behavior

• The geo-fence boundary is centered on the coordinates defined in the parent Site's configuration in GCXONE.
• If the GPS position reported by the Teltonika router exceeds 500 meters from the site center, a breach alert is generated.
• The alert clears automatically when the device returns within the defined boundary.
• Reduce the radius for permanent fixed installations; use a larger radius for mobile or semi-mobile tower deployments.

Teltonika Dashboard

Each Teltonika device has its own Dashboard tab (Configuration → the device's site → Devices → the Teltonika device → Dashboard) showing live VPN and cellular (LTE) connection status, data usage, modem temperature, SIM and uptime details, and the device's most recent GPS position on a map. A Site Radius Meters field on this screen lets you view and update the geo-fence radius directly — enter a value in meters and click Submit, instead of editing the JSON configuration by hand. If the device's last reported position is outside the configured radius, the dashboard displays a warning banner showing the current distance from the site. A Capture Now button requests a fresh GPS reading on demand, and Set Site to Current GPS updates the site's own coordinates to match the device's last known position.

Rule 5: Jammer Detection

Detects potential radio frequency jamming attempts based on sudden signal degradation and poor Reference Signal Received Quality (RSRQ). Jammer detection is critical for security-sensitive tower deployments where signal interference may indicate deliberate disruption attempts.

Default JSON Configuration

"jammerDetection": {
  "active": false,
  "criteria": {
    "signalDropThreshold": 25,
    "minSignalLevel": -113,
    "rsrqThreshold": -20
  },
  "eventCode": "modem.jammer.detected",
  "groupCode": "tower.connectivity.jamming.alert"
}

Example Behavior

• GCXONE evaluates both absolute signal level (RSRQ) and the rate of signal change (drop percentage) to distinguish genuine jamming from normal signal variation.
• An alert is triggered when the signal drop exceeds 25% OR the RSRQ falls below -20 and signal level is below -113 dBm simultaneously.
• The alert clears automatically once normal signal stability is restored.

Note: Jammer detection thresholds may need tuning based on local RF environment conditions. Sites in urban areas with natural signal variation may require a higher signalDropThreshold to reduce false positives.

Configuration Reference

Complete Teltonika Connectivity Alarm Rules JSON

The following is the complete default JSON configuration for all Teltonika connectivity alarm rules. Copy this into the Custom Alarm Rules property and modify as needed for your deployment.

"connectivityMonitoring": {
  "IOStatusChange": {
    "input": {
      "AnalogCurrentLoop": {"active": false, "low": 4, "high": 20},
      "AnalogInput": {"active": false, "low": 11, "high": 14},
      "DigitalInput": {"active": false, "ranges": ["Low level", "High level"], "alertOn": "High Level"},
      "IsolatedInput": {"active": false, "ranges": ["Low level", "High level"], "alertOn": "High Level"},
      "PowerSocketInput": {"active": false, "ranges": ["Low level", "High level"], "alertOn": "High Level"},
      "eventCode": "input.statechange",
      "groupCode": "tower.input.statechange"
    },
    "output": {
      "IsolatedOutput": {"active": false, "ranges": ["Low level", "High level"], "alertOn": "High Level"},
      "Relay": {"active": false, "ranges": ["open", "closed"], "alertOn": "open"},
      "PowerSocketOutput": {"active": false, "ranges": ["Low level", "High level"], "alertOn": "High Level"},
      "eventCode": "output.statechange",
      "groupCode": "tower.output.statechange"
    }
  },
  "simCardDataPackage": {
    "active": false,
    "simBillingStartDate": 1,
    "simDataPackageGB": 10,
    "usageWarningPercent": 80,
    "eventCode": "sim.data.usage.warning",
    "groupCode": "tower.connectivity.simdata.alert"
  },
  "cellNetworkLoss": {
    "active": false,
    "eventCode": "modem.signal.warning",
    "groupCode": "tower.connectivity.signal.alert"
  },
  "geoFencing": {
    "active": false,
    "radiusMetersWarning": 500,
    "eventCode": "geo.fence.breach",
    "groupCode": "tower.connectivity.geofence.alert"
  },
  "jammerDetection": {
    "active": false,
    "criteria": {
      "signalDropThreshold": 25,
      "minSignalLevel": -113,
      "rsrqThreshold": -20
    },
    "eventCode": "modem.jammer.detected",
    "groupCode": "tower.connectivity.jamming.alert"
  }
}

Event Codes and Group Codes Summary

Quick reference for all Teltonika connectivity event codes and group codes:

Configuration Best Practices

• Always start with Apply Default to load the complete preconfigured rule set before making changes.
• Enable rules incrementally — start with critical rules (network loss, jammer detection) before enabling threshold-sensitive rules like I/O state changes.
• Test alarm rules in a staging environment or on a single device before deploying to all sites.
• Set usageWarningPercent for SIM data at 70–80% to give operators enough time to take action before the plan is exhausted.
• For geo-fencing on permanent sites, use a small radius (100–200m). For temporary deployments, use 500m or more.
• Document your event codes and group codes in your CMS configuration to ensure correct alarm routing.

OpenVPN Configuration on Teltonika Router

From the NXGEN side, we will provide you with an OpenVPN (ovpn) configuration file and a LAN IP segment that needs to be assigned to the customer network.

Step-by-Step Configuration

Step 1: Change the Default LAN IP of the Teltonika Router to the IP Provided by the NXGEN Team

• Open the router web console.
• Navigate to Network → Interfaces → General → Edit LAN.
• Enter the LAN IP and Subnet → Save.

Step 2: Import the OpenVPN Configuration File Provided by the NXGEN Team

• On the web console, navigate to Services → VPN → OPENVPN.
• Under the Add New Interface option, provide the "VPN Name" and set the Role to "Client" → Add.

• Select "Enable OpenVPN configuration file" → Browse and attach the ovpn file.
• Select Enable and Save.

• After a couple of minutes, the status will change to "Connected".

Step 3: Test the Connectivity

• Navigate to System → Administration → Troubleshoot.
• Under Diagnostics, select the method "Ping" → Enter IP "10.10.22.42" → Perform.

• The VPN connection is successfully configured if you get a successful ping response.

Troubleshooting

Device Won't Connect

Alarm Rules Not Triggering

SIM Data Rule Not Activating

• Ensure the Teltonika router is reporting SIM data usage metrics to GCXONE.
• Verify that simDataPackageGB matches your actual SIM plan size.
• The simBillingStartDate field is currently inactive — data usage tracking uses the calendar month for now.

For additional support, contact your NXGEN representative or refer to the full GCXONE Tower Monitoring Configuration Guide which covers Victron Energy and EFOY Fuel Cell monitoring in addition to Teltonika IoT connectivity.