Prerequisite: How GB28181 Device Registration Works

Before diving into platform-specific steps, it is essential to understand the registration flow:

1. The GB28181 platform runs a SIP server that listens for device REGISTER requests.
2. Your Happytime GB28181 Device sends a SIP REGISTER message carrying its device_id and credentials to the platform's SIP server.
3. If the device_id and password match what the platform expects, the server responds with 200 OK, and the device is registered.
4. The device then sends periodic SIP heartbeat (MESSAGE) keep-alive packets at the interval specified by <heartbeat_interval>.
5. Once registered, the platform can request a live stream or playback via SIP INVITE, and the device delivers the media as a PS (Program Stream) over RTP.

Grasping this flow is key: the device must be pre-configured on the platform side before it can register successfully. The two sides must share the same device_id and password.

Universal Configuration Reference

The following table maps every gb28181device.cfg parameter to the concept it corresponds to on a generic GB28181 platform. Use this as a cross-reference when locating settings on your specific platform.

Platform 1: Hikvision iVMS-8700 / HikCentral

Hikvision's enterprise video management platforms implement GB28181 as a standard protocol module. The following steps guide you through configuring the platform side and matching the device side.

Step 1: Enable GB28181 Protocol on Hikvision Platform

1. Log in to the Hikvision platform's web management interface.
2. Navigate to System Configuration → Protocol Management → GB28181 (or equivalent).
3. Enable the GB28181 protocol module. Note the following platform-side parameters:
   • SIP Server ID — Maps to <server_id>
   • SIP Server Domain — Maps to <server_domain>
   • SIP Port — Maps to <server_port> (typically 5060)
   • SIP Protocol Type — Maps to <protocol> (UDP or TCP)

Step 2: Add the Device Entry on the Platform

1. Go to Device Management → Encoding Device.
2. Click Add and select GB28181 Device as the access protocol.
3. Fill in the device registration information:
   • Device ID — 20-digit code. This is the value you will put in <device_id>.
   • Device Name — Display name. Maps to <device_name>.
   • Password — Registration password. Maps to <password>.
   • Manufacturer / Model — Optional, for informational purposes.
4. Save the device entry. The platform is now ready to accept a REGISTER message from this device.

Step 3: Configure gb28181device.cfg for Hikvision

<config>
    <version>2016</version>
    <server_ip>192.168.1.100</server_ip>       <!-- Hikvision platform IP -->
    <server_port>5060</server_port>              <!-- Platform SIP port -->
    <server_id>34020000002000000001</server_id>   <!-- Copy from platform -->
    <server_domain>3402000000</server_domain>         <!-- Copy from platform -->
    <local_port>0</local_port>
    <device_id>34020000001110000001</device_id>     <!-- Must match platform device entry -->
    <device_name>MyHappytimeDevice</device_name>
    <password>12345678</password>                 <!-- Must match platform password -->
    <protocol>udp</protocol>                       <!-- Match platform SIP protocol -->
    <media_protocol>tcp</media_protocol>              <!-- TCP recommended for NAT traversal -->
    <reg_expires>3600</reg_expires>
    <heartbeat_interval>10</heartbeat_interval>
    <heartbeat_count>3</heartbeat_count>
    <media_base_port>19000</media_base_port>
    <log_enable>1</log_enable>
    <log_level>1</log_level>
    <log_path></log_path>
    <log_mode>loop</log_mode>
    <log_max_size></log_max_size>
    <log_max_index></log_max_index>

    <channel>
        <cid>34020000001310000001</cid>
        <cname>Camera01</cname>
        <media_url>videodevice</media_url>
        <ondemand>1</ondemand>
        <output>
            <video>
                <codec>H264</codec>
                <width></width>
                <height></height>
                <framerate></framerate>
                <bitrate></bitrate>
            </video>
            <audio>
                <codec>G711A</codec>
                <samplerate>8000</samplerate>
                <channels>1</channels>
                <bitrate></bitrate>
            </audio>
        </output>
    </channel>
</config>

Hikvision-Specific Notes

• Some Hikvision platforms require the channel ID (<cid>) to be pre-configured on the platform side as well. If the platform shows "Channel offline" even after device registration, check that the channel IDs match.
• Hikvision may enforce a maximum heartbeat interval. If registration keeps dropping, reduce <heartbeat_interval> to 10 and set <heartbeat_count> to 3.
• If the platform uses the GB28181-2022 protocol module, change <version> to 2022 and ensure all 20-digit IDs conform to the 2022 codec structure per GB/T 28181-2022 Appendix.

Platform 2: Dahua DSS / SmartPSS

Dahua DSS (Digital Surveillance System) and SmartPSS Professional both support GB28181 device access via the protocol gateway module.

Step 1: Configure the GB28181 Gateway on DSS

1. Log in to the Dahua DSS management client.
2. Navigate to System Config → Protocol → GB28181 (or Network Config → GB28181, depending on the DSS version).
3. Enable the GB28181 access service. Record the following values displayed on screen:
   • SIP Server ID — Maps to <server_id>
   • SIP Server Domain — Maps to <server_domain>
   • SIP Server Port — Maps to <server_port>

Step 2: Add the Device in DSS

1. Go to Device Management → Encoding Device.
2. Click Add and fill in:
   • Access Protocol: Select GB28181.
   • Device ID — 20-digit string. Use in <device_id>.
   • Device Name — Maps to <device_name>.
   • Password — Maps to <password>.
3. Set the device status to Online (or "enabled") so that it accepts incoming registration.

Step 3: Configure gb28181device.cfg for Dahua

<config>
    <version>2016</version>
    <server_ip>192.168.1.200</server_ip>       <!-- Dahua DSS platform IP -->
    <server_port>5060</server_port>              <!-- Platform SIP port -->
    <server_id>34020000002000000002</server_id>   <!-- Copy from DSS -->
    <server_domain>3402000000</server_domain>         <!-- Copy from DSS -->
    <local_port>0</local_port>
    <device_id>34020000001110000002</device_id>     <!-- Must match DSS device entry -->
    <device_name>MyHappytimeDevice</device_name>
    <password>12345678</password>                 <!-- Must match DSS password -->
    <protocol>udp</protocol>
    <media_protocol>tcp</media_protocol>
    <reg_expires>3600</reg_expires>
    <heartbeat_interval>10</heartbeat_interval>
    <heartbeat_count>3</heartbeat_count>
    <media_base_port>19000</media_base_port>
    <log_enable>1</log_enable>
    <log_level>1</log_level>
    <log_path></log_path>
    <log_mode>loop</log_mode>
    <log_max_size></log_max_size>
    <log_max_index></log_max_index>

    <channel>
        <cid>34020000001310000001</cid>
        <cname>Camera01</cname>
        <media_url>videodevice</media_url>
        <ondemand>1</ondemand>
        <output>
            <video>
                <codec>H264</codec>
                <width></width>
                <height></height>
                <framerate></framerate>
                <bitrate></bitrate>
            </video>
            <audio>
                <codec>G711A</codec>
                <samplerate>8000</samplerate>
                <channels>1</channels>
                <bitrate></bitrate>
            </audio>
        </output>
    </channel>
</config>

Dahua-Specific Notes

• Dahua DSS sometimes uses TCP for SIP signaling by default. If UDP registration fails, switch <protocol> to tcp and <server_port> to the platform's TCP SIP port (often 5063).
• On some DSS versions, the GB28181 module requires the channel ID prefix to match the device ID prefix. For example, if the device ID is 34020000001110000001, the channel ID should start with 3402000000111.
• If Dahua DSS reports "Device not registered" despite correct credentials, verify that firewall rules allow bidirectional UDP traffic on both the SIP port and the media port range (starting at <media_base_port>).

Platform 3: Uniview VMS

Uniview (UNV) video management systems support GB28181 device access via the platform protocol management interface.

Step 1: Activate the GB28181 Protocol Service

1. Log in to the Uniview VMS web console.
2. Navigate to System → Protocol Management → GB28181.
3. Enable the GB28181 protocol service. Note:
   • SIP Server ID — 20-digit platform identifier. Maps to <server_id>.
   • SIP Server Domain — Maps to <server_domain>.
   • SIP Port — Maps to <server_port>.

Step 2: Register the Device on Uniview VMS

1. Go to Device Management → Add Device.
2. Select GB28181 as the access method.
3. Provide:
   • Device ID — Maps to <device_id>. Must be 20 digits.
   • Device Name — Maps to <device_name>.
   • Authentication Password — Maps to <password>.

Step 3: Configure gb28181device.cfg for Uniview

<config>
    <version>2016</version>
    <server_ip>192.168.1.150</server_ip>       <!-- Uniview VMS platform IP -->
    <server_port>5060</server_port>              <!-- Platform SIP port -->
    <server_id>34020000002000000003</server_id>   <!-- Copy from Uniview VMS -->
    <server_domain>3402000000</server_domain>         <!-- Copy from Uniview VMS -->
    <local_port>0</local_port>
    <device_id>34020000001110000003</device_id>     <!-- Must match Uniview device entry -->
    <device_name>MyHappytimeDevice</device_name>
    <password>12345678</password>                 <!-- Must match Uniview password -->
    <protocol>udp</protocol>
    <media_protocol>tcp</media_protocol>
    <reg_expires>3600</reg_expires>
    <heartbeat_interval>10</heartbeat_interval>
    <heartbeat_count>3</heartbeat_count>
    <media_base_port>19000</media_base_port>
    <log_enable>1</log_enable>
    <log_level>1</log_level>
    <log_path></log_path>
    <log_mode>loop</log_mode>
    <log_max_size></log_max_size>
    <log_max_index></log_max_index>

    <channel>
        <cid>34020000001310000001</cid>
        <cname>Camera01</cname>
        <media_url>videodevice</media_url>
        <ondemand>1</ondemand>
        <output>
            <video>
                <codec>H264</codec>
                <width></width>
                <height></height>
                <framerate></framerate>
                <bitrate></bitrate>
            </video>
            <audio>
                <codec>G711A</codec>
                <samplerate>8000</samplerate>
                <channels>1</channels>
                <bitrate></bitrate>
            </audio>
        </output>
    </channel>
</config>

Uniview-Specific Notes

• Uniview VMS sometimes labels server_domain as "SIP domain" or "realm". Make sure to copy it exactly as shown on the platform GB28181 configuration page.
• In some Uniview VMS versions, the device must be added to a device group or organization unit before it will accept registration. Check that the device is assigned to a valid group.
• Uniview enforces stricter ID format validation. Both server_id and device_id must be exactly 20 numeric characters. Ensure there are no leading/trailing spaces or non-digit characters.

Verification & Troubleshooting

How to Verify Successful Registration

1. Check the log file: Enable logging (<log_enable>1</log_enable>, <log_level>1</log_level>) and look for SIP REGISTER responses. A successful registration logs an entry similar to SIP REGISTER OK or 200 OK.
2. Check the platform device list: On the platform, the device status should change from "Offline" to "Online" (or show a green indicator) within a few seconds of starting the Happytime GB28181 Device.
3. Initiate a live preview: Select the device on the platform and start a live view. If video appears, both registration and media transport are functioning correctly.

Common Registration Failures and Resolutions

Quick Checklist Before Launch

• Platform GB28181 service is enabled.
• A device entry has been created on the platform with the matching device_id and password.
• The device host can reach the platform's SIP port over the network (both TCP and UDP if applicable).
• The <server_ip>, <server_port>, <server_id>, and <server_domain> values are copied directly from the platform's GB28181 configuration page — not guessed.
• All 20-digit ID fields (server_id, device_id, cid) contain exactly 20 numeric characters with no spaces or special characters.
• Logging is enabled and you know how to view the log output.

Best Practices

• Start with One Channel: Begin with a single channel and a simple input source (e.g., videodevice or screenlive). Only add more channels after confirming that registration and streaming work end to end.
• Use TCP for Media Behind NAT: If the device and platform are on different subnets or across a VPN/WAN, set <media_protocol> to tcp. TCP media streams traverse NAT gateways and firewalls more reliably than UDP.
• Match the Platform Version First: Always ask the platform administrator which GB28181 version (2016 or 2022) the platform supports, and set <version> accordingly. Mixing versions is the most common cause of silent registration failure.
• Keep Logs During Troubleshooting: Set <log_level> to 0 (TRACE) or 1 (DEBUG) during the setup phase. The SIP REGISTER transaction details in the log are invaluable for diagnosing registration issues.
• Coordinate Device IDs with the Platform Admin: In large projects, agree on a device ID naming scheme before deployment. For example, use the geographical region code as the ID prefix to avoid collisions across sites.
• Test Cross-Version Compatibility: If your platform claims to support both GB28181-2016 and GB28181-2022, test registration with each version separately. Some platforms accept both in the UI but handle them differently at the protocol level.