Teltonika RUT Configuration¶

The RTK Base integrates with Teltonika RUT2xx series routers for mobile network connectivity. This document describes the firmware's interaction with the router for configuration, monitoring, and control.

Overview¶

The firmware communicates with the Teltonika router via HTTP RPC (ubus) over the local Ethernet connection to:

• Manage mobile network connections (4G/LTE)
• Automatically configure APN settings based on SIM card
• Monitor signal strength and connection quality
• Reboot modem or router when needed
• Fetch router credentials via QR code during production
• Configure network security (ping reboot, IP blocking)

QR Code Authentication¶

Modern Teltonika routers ship with unique credentials per device, printed on a QR code label:

• Username: Always admin
• Password: Unique per device (randomly generated)

QR Code Format¶

WIFI:T:WPA;S:RUT241_B826;P:Tj4t0HPe;SN:6002452780;
I:864081068760201;M:2097274CB824;U:admin;PW:Eq3y6HXk;B:031

Fields:

Credential Management¶

1. Storage: Credentials stored in NVS (protected partition for default, regular partition for overrides)
2. Retrieval: Base fetches QR code from rtkbase.prod.yamabikorobots.net/rtr using router MAC address
3. Fallback: If QR fetch fails, tries known default credentials in sequence:
4. admin/admin01 (factory default)
5. admin/YamabikoRTK123 (legacy)
6. admin/Make 2+2=4 (current standard)
7. root/YamabikoRTK123 (legacy root)
8. root/admin01 (root fallback)

RPC Interface¶

The firmware communicates with the router using Teltonika's RPC interface (ubus over HTTP):

int teltonika_http_rpc(const char *req, int timeout, char **resp);

RPC Categories¶

System Commands¶

Mobile Network Commands¶

Configuration Commands (UCI)¶

Common UCI configs used: - system.system - System info - network.mob1s1a1 - Mobile interface settings (APN) - network.device - Network device status - network.wireless - WiFi configuration - simcard.@sim[0] - SIM card settings - ping_reboot - Ping watchdog configuration - ip_blockd - IP blocking configuration

vuci Commands (RUT OS 7.x+)¶

Automatic APN Configuration¶

The firmware automatically configures APN settings when a SIM card is detected:

1. SIM Detection: Reads IMSI (International Mobile Subscriber Identity) or ICCID
2. APN Lookup: Looks up default APN for the carrier using app_get_default_apn_user_pswd()
3. Configuration: Sets APN, username, password via UCI:

   uci set network.mob1s1a1.apn=<apn>
   uci set network.mob1s1a1.username=<user>
   uci set network.mob1s1a1.passw=<password>
   uci commit network
   

4. Application: Mobile interface restarts with new settings

APN Database¶

The firmware includes a database mapping IMSI prefixes to carrier APN settings. This is maintained in the application layer and can be customized per deployment.

Mobile Operator Management¶

Automatic Operator Selection¶

By default, the router selects the best available operator automatically.

Manual Operator Selection¶

The RTK Base can force operator selection:

1. Scan: gsm.modem0.scan_operators returns list of available operators with:
2. Operator name
3. PLMN (Public Land Mobile Network) code

4. Network type (2G/3G/4G/5G)

5. Select: gsm.modem0.set_operator_selection with PLMN code

Example:

// Select operator by PLMN
int plmn = 20801;  // Orange France
teltonika_select_operator(plmn);

Network Security Features¶

Ping Reboot (Watchdog)¶

Automatically reboots router when network connectivity fails:

• Enabled: When configured host (default: 1.1.1.1) is unreachable
• Configuration: Via UCI ping_reboot section
• API: teltonika_set_ping_reboot_host(const char *host)

IP Blocking (Fail2ban)¶

Blocks IPs after failed connection attempts:

• Enable: teltonika_configure_ipblock(1, 20, 1)
• Max attempts: 20 failed attempts before blocking
• Reboot clear: Clear blocks on router reboot

Configuration stored in UCI ip_blockd section.

Firmware Integration¶

API Functions¶

Initialization¶

int teltonika_init(void);

Called during system startup to initialize the Teltonika module.

RPC Commands¶

// Schedule RPC request (non-blocking)
int schedule_teltonika_rpc(const char *req, int must_free);

// Execute shell command on router
int schedule_teltonika_rpc_command(const char *fmt, ...);

// Direct blocking RPC (use with caution)
int teltonika_http_rpc(const char *req, int timeout, char **resp);

Configuration¶

// Set APN configuration
int teltonika_set_apn(const char *apn, const char *user, const char *pswd);

// Set ping reboot host
int teltonika_set_ping_reboot_host(const char *host);

// Configure IP blocking
int teltonika_configure_ipblock(int enable, int max_attempt, int reboot_clear);

// Set router credentials
int teltonika_set_user(const char *value, int protected);
int teltonika_set_pswd(const char *value, int protected);

Operator Management¶

// Scan available operators
int teltonika_schedule_scan_operators(void);

// Select operator by PLMN
int teltonika_select_operator(int plmn);

Status Access¶

// Get current state structure
teltonika_info_t* teltonika_get_current_state(void);

// Check router firmware version
bool teltonika_is_v1(void);

// Check if operator control is supported
bool teltonika_operator_control(void);

State Information Structure¶

The teltonika_info_t structure contains:

typedef struct {
    teltonika_modbile_info_t mobile_info;  // Mobile network info
    struct wap {                           // WiFi AP info
        char bssid[18];
        char ssid[64];
        char pswd[64];
    } wap;
    unsigned int uptime;                   // Router uptime
    time_t time;                           // Router local time
    char serial[32];                       // Router serial
    char swver[32];                        // Firmware version
    char hw[32];                           // Hardware code
    char macaddr[18];                      // Ethernet MAC
    struct {
        int8_t enable;
        char host[18];
    } ping_reboot;
    struct {
        int recvd;
        int enabled;
        int max_attempt_count;
        int reboot_clear;
    } ip_block;
    struct moboperator operators[6];       // Scanned operators
    // ... more fields
} teltonika_info_t;

Mobile info includes: - Modem: model, manufacturer, firmware revision, IMEI - SIM: IMSI, ICCID, state (OK/PIN required/etc.) - Network: operator name, PLMN, connection type (4G/3G/etc.) - Signal: RSSI, connection state, cell ID - Data usage: bytes sent/received - Temperature: modem temperature

REST API Integration¶

The following system commands are available via /system endpoint:

Router Commands¶

Mobile Commands¶

Router Information¶

Router data is included in /get-info response under router key:

{
  "router": {
    "macaddr": "20:97:27:4C:B8:24",
    "wap-ssid": "RUT241_B826",
    "model": "RUT241",
    "imei": "864081068760201",
    "sim-iccid": "893320xxxxxxxxxxxx",
    "sim-imsi": "20810xxxxxxxxxx",
    "operator": "Orange F",
    "plmn": 20801,
    "signal": -75,
    "connected": true,
    "network-type": "4G",
    "cell-id": "12345678"
  }
}

Console Commands¶

Available via serial console or debug interface:

# Show router information
teltonika info

# Set router credentials
teltonika set_user <username>
teltonika set_pswd <password>

# Scan mobile operators
teltonika scan

# Select operator by PLMN code
teltonika select <PLMN>

# Reboot router
teltonika reboot

# Reboot modem
teltonika reboot-modem

Error Handling¶

The firmware handles various error conditions:

1. Authentication Failure: Automatically tries next credential in table
2. Session Expired: Re-authenticates automatically
3. Network Unreachable: Marks router as offline, retries periodically
4. RPC Timeout: Uses extended timeout for slow operations (scanning, modem info)
5. Invalid Response: Logs error, continues operation

Version Compatibility¶

The firmware supports both RUT OS versions:

• RUT OS v1.x (Legacy): Uses different RPC methods
• RUT OS v7.x+ (Current): Uses vuci interface

Version detection is automatic via firmware version string parsing.

Security Considerations¶

1. Credential Storage: Router passwords stored in NVS protected partition
2. HTTPS: QR code fetched over HTTPS with certificate validation
3. Session Management: RPC sessions expire and auto-renew
4. Password Policy: Production routers use strong, unique passwords
5. IP Blocking: Protects against brute force attacks

Troubleshooting¶

Router Not Detected¶

1. Check Ethernet cable connection
2. Verify router is powered on
3. Check base logs for ARP entries
4. Confirm router MAC address is in database

QR Code Fetch Failed¶

1. Verify Ethernet IP is acquired
2. Check DNS resolution works
3. Confirm MAC address matches QR database
4. Fallback to default credentials

Mobile Connection Issues¶

1. Check SIM card is inserted and recognized
2. Verify antenna is connected
3. Review signal strength in logs
4. Check APN settings are correct for carrier
5. Try manual operator selection

RPC Failures¶

1. Check router responds to ping
2. Verify credentials are correct
3. Review session state
4. Check for firmware compatibility
5. Review router system logs

References¶

• Production Flow - QR code retrieval process
• REST API - HTTP endpoints documentation
• Teltonika Wiki - Official router documentation
• RUT OS RPC Documentation - Teltonika RPC reference