Why Registration Matters

In the GB28181 ecosystem, a device is invisible to the platform until it successfully registers. Registration establishes the device's identity, its network address, and its availability for media sessions. A device that loses registration is effectively offline — the platform cannot initiate live preview, PTZ control, recording playback, or audio talk with it.

Understanding the registration lifecycle is critical because:

• Registration failures are the most common GB28181 integration issue encountered in the field.
• Network instability (packet loss, firewall timeouts, NAT rebinding) can silently deregister a device while the application appears to be running normally.
• Misconfigured timers (registration expiry and heartbeat intervals) can cause platforms to drop devices or devices to generate excessive SIP traffic.

This guide explains the complete registration lifecycle from the first SIP REGISTER message through heartbeat maintenance to automatic reconnection, using the Happytime GB28181 Device as the reference implementation.

The GB28181 Registration Lifecycle: Four Phases

GB28181 device registration follows a four-phase lifecycle implemented over the SIP protocol (RFC 3261). Each phase has corresponding configuration parameters in gb28181device.cfg.

Phase 1: REGISTER           Phase 2: KEEP-ALIVE         Phase 3: EXPIRY          Phase 4: RECOVERY
+------------------------+  +--------------------------+  +---------------------+  +------------------------+
| Device sends SIP       |  | Device sends periodic    |  | If MESSAGE responses |  | Device detects failure |
| REGISTER to platform.  |  | MESSAGE heartbeats at    |  | stop arriving, the   |  | and automatically re-  |
| Platform authenticates |  | <heartbeat_interval>    |  | heartbeat_count      |  | REGISTERs according   |
| and returns 200 OK.    |  | Platform responds with   |  | threshold triggers   |  | to heartbeat_count.   |
|                        |  | 200 OK for each MESSAGE. |  | emergency re-REGISTER|  |                        |
|                        |  |                          |  |                      |  | REGISTER also re-sent |
| Config: <protocol>,    |  | Config: <heartbeat_     |  | Config: <heartbeat_  |  | at <reg_expires>      |
| <reg_expires>         |  | interval>               |  | count>               |  | interval proactively. |
+------------------------+  +--------------------------+  +---------------------+  +------------------------+

The four parameters that control this lifecycle are:

Phase 1: SIP REGISTER — Initial Device Registration

How It Works

When the GB28181 Device starts, it sends a SIP REGISTER request to the platform's SIP server at <server_ip>:<server_port>. The REGISTER message contains:

• Request-URI: sip:<server_id>@<server_domain> — identifies the target SIP server.
• From / To headers: sip:<device_id>@<server_domain> — the device's identity.
• Contact header: The device's reachable SIP URI (IP:port) for incoming INVITE requests.
• Expires header: <reg_expires> (default 3600) — tells the platform how long this registration is valid.
• Authorization header: Contains the digest authentication response using the <password>.

SIP REGISTER Transaction Flow

GB28181 Device                          SIP Server (Platform)
     |                                          |
     |---- REGISTER sip:34020000002000000001 --->|
     |     From: sip:34020000001110000001        |
     |     Expires: 3600                         |
     |     (no Authorization header)              |
     |                                           |
     |<--- 401 Unauthorized ---------------------|
     |     WWW-Authenticate: Digest realm=...     |
     |                                           |
     |---- REGISTER (with Authorization) ------->|
     |     Authorization: Digest username=...    |
     |     response=MD5(HA1:nonce:HA2)           |
     |                                           |
     |<--- 200 OK -------------------------------|
     |     Expires: 3600                         |
     |                                           |
     |  [Device is now registered. Platform can  |
     |   send INVITE for live preview/playback.]  |

The Authentication Handshake

GB28181 uses SIP Digest Authentication (RFC 2617). The device's first REGISTER attempt does not include credentials. The platform responds with 401 Unauthorized containing a WWW-Authenticate header with a nonce (a server-generated random string). The device then re-sends the REGISTER with an Authorization header containing:

• username: The <device_id>
• realm: The <server_domain>
• nonce: The nonce from the 401 response
• response: The computed digest: MD5( MD5(username:realm:password) : nonce : MD5(REGISTER:Request-URI) )

If the password in gb28181device.cfg matches the password configured for this <device_id> on the platform, the platform returns 200 OK and the device is registered.

Phase 2: SIP MESSAGE — Heartbeat Keep-Alive

Why Heartbeats Are Necessary

After registration, the platform knows the device exists at a particular IP:port. However, network conditions can change silently. The device's IP address could be reassigned by DHCP, a NAT mapping could expire, or the device could crash without sending a proper SIP DEREGISTER. Without a heartbeat mechanism, the platform has no way to detect that a registered device has become unreachable until it tries to initiate a media session (e.g., live preview) and fails.

The GB28181 standard uses SIP MESSAGE as the heartbeat mechanism. The device sends a MESSAGE to the platform at fixed intervals, and the platform responds with 200 OK. This serves two purposes:

1. Liveness detection: The platform knows the device is still online.
2. NAT keep-alive: The periodic UDP traffic prevents NAT gateways from timing out the SIP port mapping.

MESSAGE Heartbeat Flow

GB28181 Device                          SIP Server (Platform)
     |                                          |
     |  [Every <heartbeat_interval> seconds]    |
     |---- MESSAGE sip:server_id@server_domain ->|
     |     CmdType: Keepalive                    |
     |     DeviceID: 34020000001110000001        |
     |     Status: OK                            |
     |                                           |
     |<--- 200 OK -------------------------------|
     |                                           |
     |  [Platform marks device as active.        |
     |   Heartbeat counter is reset on device.]   |

The heartbeat MESSAGE payload is an XML body (MIME type Application/MANSCDP+xml) containing:

• CmdType: Keepalive — identifies this as a heartbeat message.
• DeviceID: The <device_id> that was registered.
• Status: OK indicating normal operation.

The <heartbeat_interval> Parameter

This parameter controls how frequently heartbeats are sent. The default interval is 10 seconds. The trade-off:

Recommendation: Use 10 for small deployments (fewer than 100 devices) and for initial integration testing. Increase to 30 or 60 for large-scale deployments, but ensure the platform's SIP server and any intermediate NAT gateways can accommodate the longer interval.

Phase 3: Registration Expiry — The <reg_expires> Timer

How Registration Expiry Works

When the platform returns 200 OK to the REGISTER request, it includes an Expires header. The device's registration is valid for <reg_expires> seconds (default 3600, or 1 hour). The device must send a new REGISTER request before this timer expires to refresh its registration.

Happytime GB28181 Device automatically re-REGISTERs at 50% of the expiry interval. For the default expiry of 3600 seconds, this means a re-REGISTER is sent every 1800 seconds (30 minutes). This provides a generous safety margin for network delays.

Important: The heartbeat MESSAGE mechanism does not extend the registration lifetime. Even if heartbeats are being exchanged successfully, the device must still re-REGISTER before <reg_expires> elapses. These are two independent timers:

• Heartbeat: Short-term liveness check (seconds).
• Registration Expiry: Long-term session renewal (hours).

Choosing the Right Expiry Value

Note: Some platforms enforce a maximum registration lifetime. If you set <reg_expires> to a value higher than the platform's maximum, the platform will override it with its own limit in the 200 OK response.

Phase 4: Auto-Reconnection — The <heartbeat_count> Safety Net

The Heartbeat Timeout Mechanism

Under normal operation, the platform responds to every heartbeat MESSAGE with 200 OK. If the platform stops responding (due to server restart, network partition, or firewall rule change), the device detects this and takes action.

The <heartbeat_count> parameter defines the threshold: how many consecutive heartbeat responses can be missed before the device concludes that registration has been lost and initiates an emergency re-REGISTER.

GB28181 Device                          SIP Server (Platform)
     |                                          |
     |  [Normal: heartbeats sent every           |
     |   <heartbeat_interval> seconds]          |
     |---- MESSAGE (hb=1) ---------------------->|
     |<--- 200 OK -------------------------------|
     |---- MESSAGE (hb=2) ---------------------->|
     |<--- 200 OK -------------------------------|
     |                                          |
     |  [*** Platform goes offline ***]          |
     |                                          |
     |---- MESSAGE (hb=3) --X    (no response)   |
     |---- MESSAGE (hb=4) --X    (missed=2)      |
     |---- MESSAGE (hb=5) --X    (missed=3)      |
     |                                          |
     |  [If heartbeat_count=3, threshold met]    |
     |  [Device triggers emergency re-REGISTER]  |
     |---- REGISTER (emergency re-reg) --------->|
     |                                         |
     |  [If platform is back online, it responds |
     |   with 200 OK. If not, device keeps       |
     |   retrying REGISTER periodically.]        |

Understanding <heartbeat_count>=0 (Default)

The default value of 0 means heartbeat timeout detection is disabled. With this setting:

• The device continues sending heartbeat MESSAGEs at the configured interval.
• If the platform stops responding, the device does not notice and continues operating as if registered.
• The device will re-REGISTER only when the <reg_expires> timer elapses (every 30 minutes by default).
• During the gap between platform failure and the next scheduled re-REGISTER, the platform cannot reach the device.

This default is chosen for compatibility: some platforms do not respond to MESSAGE heartbeats with 200 OK, and enabling heartbeat timeout detection would cause the device to perpetually re-REGISTER.

When to Enable Heartbeat Timeout Detection

Set <heartbeat_count> to a non-zero value (e.g., 3) when:

• The platform reliably responds to MESSAGE heartbeats.
• Fast recovery from platform failures is critical (e.g., alarm monitoring, real-time surveillance).
• The network is known to be unstable and silent connection drops are frequent.

With <heartbeat_interval>=10 and <heartbeat_count>=3, the device detects platform failure in approximately 30 seconds (10 seconds per heartbeat × 3 missed responses) plus any network propagation delay.

Registration Configuration Reference

Below is the complete registration-related section of gb28181device.cfg with documentation for each parameter:

<version>2016</version>                         <!-- gb28181 version: 2016 or 2022 -->
<server_ip>192.168.3.36</server_ip>             <!-- SIP server IP (IPv4, IPv6, or domain) -->
<server_port>5060</server_port>                 <!-- SIP server port (default 5060) -->
<server_id>34020000002000000001</server_id>     <!-- Platform SIP server ID (20 digits) -->
<server_domain>3402000000</server_domain>       <!-- Platform domain (first 10 digits of server_id) -->
<local_port>0</local_port>                      <!-- Local SIP port (0=auto-assign) -->
<device_id>34020000001110000001</device_id>     <!-- Device ID (20 digits, must match platform) -->
<device_name>Happytimesoft</device_name>        <!-- Device display name -->
<password>12345678</password>                   <!-- Registration password -->
<protocol>udp</protocol>                        <!-- SIP signaling transport: udp or tcp -->
<reg_expires>3600</reg_expires>                 <!-- Registration expiry in seconds -->
<heartbeat_interval>10</heartbeat_interval>     <!-- Heartbeat interval in seconds -->
<heartbeat_count>0</heartbeat_count>            <!-- Missed heartbeats before re-register (0=disabled) -->

Recommended Configurations for Different Scenarios

Scenario A: Development and Integration Testing

Fast heartbeat and aggressive timeout detection help identify configuration issues quickly.

<protocol>udp</protocol>
<reg_expires>600</reg_expires>
<heartbeat_interval>5</heartbeat_interval>
<heartbeat_count>3</heartbeat_count>

Re-registers every 5 minutes. Detects platform failure within ~15 seconds. Useful for rapid debugging.

Scenario B: Small Production Deployment (< 100 devices)

Balanced settings suitable for a small site with a single GB28181 platform.

<protocol>udp</protocol>
<reg_expires>3600</reg_expires>
<heartbeat_interval>10</heartbeat_interval>
<heartbeat_count>3</heartbeat_count>

Standard settings with heartbeat timeout detection enabled. Re-registers every 30 minutes, detects failure within ~30 seconds.

Scenario C: Large-Scale Deployment (> 1000 devices)

Reduced heartbeat frequency to minimize SIP load on the platform. Heartbeat timeout detection is disabled to avoid false-positives from platform queue delays.

<protocol>tcp</protocol>
<reg_expires>3600</reg_expires>
<heartbeat_interval>30</heartbeat_interval>
<heartbeat_count>0</heartbeat_count>

TCP signaling for connection-oriented reliability. Longer heartbeat interval reduces per-device SIP load by 3x compared to the default. Heartbeat timeout detection is disabled to prevent mass re-registration storms if the platform briefly becomes overloaded.

Scenario D: Unreliable Network (Satellite, Mobile, Industrial)

Aggressive re-registration to recover quickly from intermittent connectivity loss.

<protocol>tcp</protocol>
<reg_expires>600</reg_expires>
<heartbeat_interval>10</heartbeat_interval>
<heartbeat_count>2</heartbeat_count>

TCP for reliability. Short registration expiry for fast recovery. Heartbeat timeout detection triggers after 2 missed heartbeats (~20 seconds).

Troubleshooting Registration Failures

Best Practices

• Start with <heartbeat_count>=0 During Initial Integration: Disable heartbeat timeout detection when first connecting to a new platform. Once you confirm the platform responds to MESSAGE heartbeats with 200 OK, enable <heartbeat_count> for failure detection.
• Use TCP for SIP Signaling When Behind NAT: If the device is behind a NAT router, <protocol>tcp</protocol> is more reliable than UDP. TCP connections are maintained statefully by firewalls and are less likely to be silently dropped by intermediate network devices.
• Never Set <heartbeat_interval> Longer Than the NAT Timeout: If using UDP, the heartbeat interval must be shorter than the NAT UDP mapping timeout. For consumer-grade routers, this is typically 30-60 seconds. For carrier-grade NAT, it may be as low as 15-20 seconds. When in doubt, use 10 seconds.
• Monitor Re-REGISTER Frequency in Logs: If the log shows re-REGISTERs occurring more frequently than expected (e.g., every few minutes with <reg_expires>3600</reg_expires>), either the platform is overriding the expiry to a shorter value, or heartbeat timeout detection is triggering unnecessary re-REGISTERs.
• Synchronize <reg_expires> with Platform Policy: Ask the platform administrator for the maximum allowed registration lifetime. Setting <reg_expires> higher than the platform's maximum is harmless — the platform will return a lower value in the 200 OK — but the log may show a discrepancy that causes confusion during troubleshooting.
• Logging is Your Best Diagnostic Tool: Set <log_level>1</log_level> (DEBUG) during integration. The detailed SIP transaction logs show the exact REGISTER, 401 challenge, re-REGISTER, MESSAGE heartbeat, and 200 OK exchanges. These logs are the fastest way to pinpoint which step in the registration lifecycle is failing.