Connect a GB/T 32960 device via Cloud Gateway (one-way TLS)

Prerequisites

• An Exclusive Enterprise Edition instance is available. This example uses the China (Shanghai) region.

  Purchase an Enterprise Edition instance.

• Custom certificates are prepared.

  Required files: root certificate (root-ca.crt), server private key (server.key), and server certificate (server.crt).

  Generate these with OpenSSL. Generate a custom certificate.

Background

The IoT Platform cloud gateway supports GB/T 32960 connections over TCP or TLS. TLS is recommended and supports server-side one-way verification, device-side OCSP, and mutual TLS.

This example uses TLS with server-side one-way verification.

For protocol details, see GB/T 32960 protocol cloud gateway overview.

The GB/T 32960 open source client is available on GitHub.

Prepare the environment

• Git and Patch are installed on your operating system.

• A Java development environment is configured:

  • JDK version: JDK 8

  • Integrated development environment (IDE): IntelliJ IDEA Community Edition

Download the source code

Clone the demo and apply a patch file:

1. Run the following commands to clone the tsp demo repository.

   git clone https://github.com/zhengyishan/tsp.git
   cd tsp
   git checkout 5ef2907b7160f74cf4948b641d75fccd50c5dd6a -b demo_branch

2. Download the patch file gb32960.patch to the tsp directory.

3. Run the following command to apply the patch to the tsp demo file.

   patch -p1 < gb32960.patch

Create a cloud gateway and devices

1. Log on to the IoT Platform console.

2. In the top-left corner of the console, select the region where your IoT Platform instance is located.

3. On the Instance Details page, click the target Exclusive Enterprise Edition instance.

4. In the left-side navigation pane, choose Devices > Cloud Gateway, and click Add Cloud Gateway.

5. In the dialog box that appears, set Server Certificate Private Key to the content of the server.key file and set Server Certificate to the content of the server.crt file.

   For parameter details, see Add a cloud gateway.

   Set Cloud Gateway Name to GBtest, Protocol to GB/T 32960, and Custom Port Number to 8999. Select server-side one-way verification for Authentication Type and TLS for Transport Protocol. Select No for Enable Device X.509 Certificate Authentication and Disable for Enable OCSP.

6. Click OK.

7. After the cloud gateway is created, find it in the gateway list and copy the Gateway URL.

   The Gateway URL format is xxx.igw.iothub.aliyuncs.com(Port number: 8999). Save the full URL.

Add devices

1. In the left-side navigation pane, choose Devices>Products. Find the product for the cloud gateway that you created, and then click Manage Devices in the Actions column.

2. On the Devices page, click Batch Add.

3. In the Batch Add Devices dialog box, click Download .csv Template.

   In the dialog box, the Product is already selected as your cloud gateway. The dialog box also contains the Batch Upload File field and the Upload File button.

4. In the template, enter a VIN, such as device10000000001. Then, save the file with a .csv extension.

   Important

   A VIN is a vehicle identification number. It can be up to 17 characters in length and can contain letters and digits.

5. Return to the Batch Add Devices dialog box. Click Upload File to upload the file you just saved, and then click OK.

   After the file is uploaded, a Parsing complete message appears along with the Total devices count. Verify the parsing result and click OK.

   After the device identities are imported, IoT Platform creates the corresponding devices and uses the uploaded VIN values as the DeviceName for the devices. The created devices appear in the device list.

   The status of a new device is inactive.

Develop the device client

Develop a Java client to connect device device10000000001 to IoT Platform.

1. Open IntelliJ IDEA and import the tsp demo that you downloaded.

2. In the project, import the root certificate file root-ca.crt to the /dyy-gateway-tcu/src/main/resources directory.

3. Open the /dyy-gateway-tcu/src/main/java/com/dyy/tsp/gateway/tcu/config/TcuProperties.java file in the project and modify the device connection parameters.

   Replace the following parameters with your actual values:

       // The domain name of the gateway. TODO: Replace this with the domain name of your cloud gateway instance.
       private String gatewayHost = "iot-*******.igw.iothub.aliyuncs.com";
       // The port of the gateway. TODO: Replace this with the port of your cloud gateway instance.
       private Integer gatewayPort = 8999;
       // Specifies whether to use TLS. TODO: If you use a direct TCP connection, set this to false.
       private boolean useSSL = Boolean.TRUE;
       // If you do not use TLS, ignore this. If you use TLS, set the path of the root certificate file root-ca.crt.
       private String CA_PATH = "dyy-gateway-tcu/src/main/resources/root-ca.crt";
       // The vehicle identification number. The value must be 17 bytes in length. TODO: Replace this with the VIN of your vehicle and use this VIN to create a device in the console.
       private String vin = "device10000000001";

   Parameter	Example	Description
   gatewayHost	iot-*******.igw.iothub.aliyuncs.com	The endpoint of the GB/T 32960 protocol cloud gateway. This is the domain name part of the Gateway URL of your cloud gateway.
   gatewayPort	8999	The custom port number for the cloud gateway endpoint. Default value: 8999. This is the port number part of the Gateway URL of your cloud gateway.
   useSSL	Boolean.TRUE	Specifies whether to connect by using TLS. Valid values: Boolean.TRUE (default): Use TLS. Boolean.FALSE: Use TCP.
   CA_PATH	dyy-gateway-tcu/src/main/resources/root-ca.crt	To connect by using TLS, set this parameter to the absolute path of the root-ca.crt file in your project.
   vin	device10000000001	The vehicle identification number. This is the VIN of the cloud gateway device that you created.

4. The /dyy-gateway-tcu/src/main/java/com/dyy/tsp/gateway/tcu/handler/BusinessHandler.java file handles vehicle login, heartbeats, real-time data reporting, and vehicle logout. Modify this file to add custom features.

Run the device client

1. In IntelliJ IDEA, choose File > Project Structure.

2. Set Project SDK to version 1.8 and click Apply.

3. Click OK.

4. Run the main program in the TcuApplication.java file.

   After the server-side verification is successful, the device goes online.

View run logs

Device-side run logs

The device client prints upstream and downstream messages:

• A request message for vehicle login. The third and fourth bytes of the message, 01 fe, indicate a vehicle login request.

           +-------------------------------------------------+
           |  0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f |
  +--------+-------------------------------------------------+----------------+
  |00000000| 23 23 01 fe 31 32 33 34 35 36 37 38 39 30 31 32 |##..device100000|
  |00000010| 33 34 35 36 37 01 00 1e 17 05 06 10 23 19 00 01 |00001.......#...|
  |00000020| 31 32 33 34 35 36 37 38 39 30 31 32 33 34 35 36 |1234567890123456|
  |00000030| 37 38 39 30 00 00 ee                            |7890...         |
  +--------+-------------------------------------------------+----------------+

• A response message from the server for the device login request. The third and fourth bytes, 01 01, indicate that the vehicle login is successful.

           +-------------------------------------------------+
           |  0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f |
  +--------+-------------------------------------------------+----------------+
  |00000000| 23 23 01 01 31 32 33 34 35 36 37 38 39 30 31 32 |##..device100000|
  |00000010| 33 34 35 36 37 01 00 1e 17 05 06 10 23 19 00 01 |00001.......#...|
  |00000020| 31 32 33 34 35 36 37 38 39 30 31 32 33 34 35 36 |1234567890123456|
  |00000030| 37 38 39 30 00 00 11                            |7890...         |
  +--------+-------------------------------------------------+----------------+

• A message for reporting a heartbeat. The third and fourth bytes, 07 fe, indicate that the message is an upstream heartbeat.

           +-------------------------------------------------+
           |  0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f |
  +--------+-------------------------------------------------+----------------+
  |00000000| 23 23 07 01 31 32 33 34 35 36 37 38 39 30 31 32 |##..device100000|
  |00000010| 33 34 35 36 37 01 00 00 36                      |00001...6       |
  +--------+-------------------------------------------------+----------------+

• A response message from the server for the heartbeat message. The third and fourth bytes, 07 01, indicate that the message is a downstream heartbeat.

           +-------------------------------------------------+
           |  0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f |
  +--------+-------------------------------------------------+----------------+
  |00000000| 23 23 07 01 31 32 33 34 35 36 37 38 39 30 31 32 |##..device100000|
  |00000010| 33 34 35 36 37 01 00 00 36                      |00001...6       |
  +--------+-------------------------------------------------+----------------+

• A message for reporting real-time data. The third and fourth bytes, 02 fe, indicate a real-time data report.

           +-------------------------------------------------+
           |  0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f |
  +--------+-------------------------------------------------+----------------+
  |00000000| 23 23 02 fe 31 32 33 34 35 36 37 38 39 30 31 32 |##..device100000|
  |00000010| 33 34 35 36 37 01 00 14 17 05 06 10 23 23 08 01 |00001.......##..|
  |00000020| 01 00 05 00 06 00 04 00 07 01 00 0a df          |.............   |
  +--------+-------------------------------------------------+----------------+