Integration with Smart Vehicle Service

Last Updated on : 2024-06-19 08:20:14download

This topic describes how to integrate the smart vehicle service with the Tuya Developer Platform by using Tuya IoT Edge Gateway.

Architecture

Tuya provides a comprehensive solution to help integrate the smart vehicle service with the Tuya Developer Platform. The architecture of the solution is shown as follows.

Integration with Smart Vehicle Service

The vehicle service gateway communicates with Tuya’s IoT Edge Gateway over the MQTT protocol.

Business process

Tuya Developer PlatformIoT Edge GatewayDevice GatewaySynchronize the device informationActivate the deviceReturn the resultReturn the resultSend control commands from the cloudSend commandsReturn the execution resultReturn the resultReport device propertiesReport device propertiesReturn the processing resultReturn the resultRegularly report device online and offline eventsReport device online and offline eventsTuya Developer PlatformIoT Edge GatewayDevice Gateway

Device features

Request type Device capability Functional description Data transfer type
1 Send a command to synchronize the parking lot information Synchronize the information about the specified parking lot. Send
2 Report the parking lot information Report the information about the specified parking lot. Report
3 Send a command to synchronize device data The IoT Edge Gateway sends a request for synchronizing the device list, and the vehicle service gateway synchronizes the device list. Send
4 Report the device data synchronizing message The IoT Edge Gateway sends a request for synchronizing the device list. After receiving the request, the vehicle service gateway reports the information about the smart vehicle devices to the IoT Edge Gateway. Report
5 Send a command to add a permanent vehicle Add a permanent vehicle with long-term payment plans. Send
6 Send a command to modify a permanent vehicle Modify a permanent vehicle with long-term payment plans. Send
7 Send a command to delete a permanent vehicle Delete a permanent vehicle with long-term payment plans. Send
8 Send a command to permit the pass of an unlicensed vehicle Permit the pass of an unlicensed vehicle. Send
9 Send a command to add a visitor vehicle Add a visitor vehicle. Send
10 Send a command to modify a visitor vehicle Modify a visitor vehicle. Send
11 Send a command to delete a visitor vehicle Delete a visitor vehicle. Send
12 Send a command to extend a visitor vehicle Extend the accessible period of a visitor vehicle. Send
13 Send a command to generate a pending order Generate a pending order. Send
14 Send a command to notify the vehicle service gateway of payment result Send a notification of a payment result. Send
15 Send a command to lock a vehicle Lock a vehicle. Send
16 Send a command to unlock a vehicle Unlock a vehicle. Send
17 Send a command to add a special vehicle Add a special vehicle. Send
18 Send a command to delete a special vehicle Delete a special vehicle. Send
19 Report a license plate update event Update the license plate of the specified vehicle. Report
20 Send a command to synchronize data Synchronize the data. Send
21 Report a payment event Report a payment event. Report
22 Report an access event Report an access event. Report
23 Report the device status Report the event that the specified device gets online or offline. Report
24 Send a command to query the current vehicle Query the current vehicle at the barrier gate. Send
25 Send a command to control a barrier gate Control the specified barrier gate. Send

Integration protocol

During communications over the MQTT protocol, the vehicle service gateway works as a client, and Tuya IoT Edge Gateway works as a broker.

Connection authentication

  • ip: the IP address of the MQTT broker. It is provided by Tuya during joint debugging on the Tuya Developer Platform.

  • port: the port number of the MQTT broker. It is provided by Tuya during joint debugging on the Tuya Developer Platform.

  • clientId: the client ID of the vehicle service gateway.

  • username: the manufacturer username of the vehicle service gateway. It is provided by Tuya during joint debugging on the Tuya Developer Platform.

  • password: sub(md5(clientId + username), 0, 16). Here is an example to generate a password:

    clientId: abcd1234
    username: tuya
    password: sub(md5(clientId + username), 0, 16)-> c88ba730489ed678
    

ip, port, clientId, and username must be configured in the vehicle service gateway in advance. This enables the vehicle service gateway to read these parameters every time it starts and thus connect to the IoT Edge Gateway.

Message topic reported by vehicle service gateway

Push: gateway/vehicle/out/{clientId}
payload: base64.Encode(aes.encrypt(payload, password))

Sample message

password: "f4ae303385f24fc8"
payload: `{"t":1655200901,"reqId":"1655200901125274008","reqType":2,"data":{}}`
secPayload: "WMnpAqV9Diuz9hbhb5U5zMN3jgGubWaPGT3xDbY0QnUDy6B72W9pH0Li/cRN5i17dQnWqWZKnkicTZHv0G6WkKtFoEE6dkho0FhVAXOxNiY="

Message topic subscribed by vehicle service gateway

Push: gateway/vehicle/in/{clientId}
payload: base64.Decode(aes.decrypt(payload, password))

Sample message

password: "f4ae303385f24fc8"
secPayload: "WMnpAqV9Diuz9hbhb5U5zMN3jgGubWaPGT3xDbY0QnUDy6B72W9pH0Li/cRN5i17dQnWqWZKnkicTZHv0G6WkKtFoEE6dkho0FhVAXOxNiY="
payload: `{"t":1655200901,"reqId":"1655200901125274008","reqType":1,"data":{}}`

Message encryption and decryption

Messages sent and received by devices must be encrypted and decrypted by AES.

  • The message body is serialized and deserialized using JSON.
  • The encryption and decryption method: AES-ECB.
  • The encryption and decryption password: Use the password created for connection authentication.

Sample code

password := "f4ae303385f24fc8"
payload := `{"t":1655199371,"reqId":"1655199371114618671","reqType":1,"data":null}`
data, err := aes_crypto.AesECBEncrypt([]byte(payload), []byte(password))
fmt.Println(err)
base64str := base64.StdEncoding.EncodeToString(data)
fmt.Println(base64str)

dataE, err := base64.StdEncoding.DecodeString(base64str)
fmt.Println(err)
dataD, err := aes_crypto.AesECBDecrypt(dataE, []byte(password))
fmt.Println(err)
fmt.Println(string(dataD))

Device management

Send a command to synchronize the parking lot information

It is used for vehicle service synchronization. After the vehicle service gateway is connected to the MQTT server of Tuya IoT Edge Gateway, send a command to synchronize the vehicle service information. After receiving the command, the vehicle service gateway reports the parking lot information.

Request parameter

Parameter Type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer When the value of reqType is 1, synchronize the information about a specified parking lot. Yes
data Object The business data. Yes

Message format

{
	"t": 159801061****,
	"reqId": 123123****,
	"reqType": 1,
	"data": {}
}

Report the parking lot information

The vehicle service gateway reports the parking lot information. Then, Tuya IoT Edge Gateway adds or updates the reported parking lot information, and returns the results.

Request parameter

Parameter Type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer When the value of reqType is 2, report the information about a specified parking lot. Yes
data Object The business data. Yes
+ parkId String The ID of a specified parking lot. The maximum length is 64 characters. Yes
+ parkName String The name of a specified parking lot. Yes
+ totalSpaceNum Integer The total number of parking spaces. Yes
+ freeSpaceNum Integer The number of available parking spaces. Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 2,
    "data": {
        "parkId": "parkId***",
        "parkName": "Virtual Parking Lot",
        "totalSpaceNum": 1000,
        "freeSpaceNum": 910
    }
}

Send a command to synchronize device data

Synchronize the device data. After the vehicle service gateway is connected to the MQTT server of Tuya IoT Edge Gateway, send a command to synchronize the device data. After receiving the command, the vehicle service gateway reports the device data.

Request parameter

Parameter Type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer When the value of reqType is 3, synchronize the device data. Yes
data Object The business data. Yes

Message format

{
	"t": 159801061***,
	"reqId": 123123***,
	"reqType": 3,
	"data": {}
}

Report the device data synchronizing message

The vehicle service gateway reports the device data. Then, Tuya IoT Edge Gateway adds or updates the reported device data, and returns the results.

Request parameter

Parameter Type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer When the value of reqType is 4, report the device data synchronizing message. Yes
data Object The business data. Yes
+ devs Array The list of devices. Yes
++ cid String The ID of a specified third-party device. It can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI. The maximum length is 64 characters. Yes
++ deviceName String The name of a specified device. The maximum length is 64 characters. Yes
++ installLocation String The location where the device is installed. The maximum length is 64 characters. No
++ deviceIp String The IP address of a specified device. The maximum length is 64 characters. No
++ deviceType String The operation type of a specified device. Valid values:
  • 1: enter
  • 2: exit
Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 4,
    "data": {
        "devs": [
            {
                "cid": "vehicle***",
                "parkId": "parkId***",
                "deviceName": "Entry Barrier Gate",
                "installLocation": "Virtual Parking Lot",
                "deviceIp": "192.168.1.***",
                "deviceType": "1"
            },
            ...
        ]
    }
}

Report device status

Report the event that a specified device gets online or offline. Then, Tuya IoT Edge Gateway updates the status and returns the results.

Request parameter

Parameter Type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer When the value of reqType is 23, report the status of a specified device. Yes
data Object The business data. Yes
+ cid String The ID of a specified third-party device. It can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI. The maximum length is 64 characters. Yes
+ online Integer The device status.
  • 1: A device goes offline.
  • 2: A device goes online.
Yes

Response parameter

Parameter Type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer When the value of reqType is 2, report the information about a specified parking lot. Yes
data Object The business data. Yes
+ success Boolean The returned result.
  • true: The call is successful.
  • false: The call failed.
Yes
+ msg String The response result. Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 23,
    "data": {
        "cid": "vehicle***",
        "online": 1
    }
}

Response message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 23,
    "data": {
        "success": true,
        "msg": "success"
    }
}

Send a command to query the current vehicle

Query the information about the current vehicle based on cid. After receiving the command, the vehicle service gateway queries the information about the current vehicle at the barrier gate, and then reports the results.

Request parameter

Parameter Type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer When the value of reqType is 24, send a command to query the current vehicle. Yes
data Object The business data. Yes
+ cid String The ID of a specified third-party device. It can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI. The maximum length is 64 characters. Yes

Response parameter

Parameter Type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer When the value of reqType is 24, query the information about the current vehicle at the barrier gate. Yes
data Object The business data. Yes
+ success Boolean The returned result.
  • true: The call is successful.
  • false: The call failed.
Yes
+ msg String The response result. Yes
+ plateNo String The license plate number in the format of A-B0KPTX. The maximum length is 64 characters. Yes
+ captureTime Long The 13-digit timestamp of the query time. Unit: milliseconds. Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 24,
    "data": {
        "cid": "vehicle***"
    }
}

Message format of returned result

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 24,
    "data": {
        "success": true,
        "msg": "success",
        "plateNo": "A-B0K123",
        "captureTime": 1655284422123,
    }
}

Send a command to control a barrier gate

Send a command to control a barrier gate. After receiving the command, the vehicle service gateway operates the barrier gate and reports the results.

Request parameter

Parameter Type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer When the value of reqType is 25, send a command to control a barrier gate. Yes
data Object The business data. Yes
+ cid String The ID of a specified third-party device. It can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI. The maximum length is 64 characters. Yes
+ openModel Integer The operation type of a specified barrier gate. Valid values:
  • 1: Open the barrier gate.
  • 2: From lifting the barrier to closing the gate
  • 3: Enable the normally open mode
  • 4: Disable the normally open mode
Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 25,
    "data": {
        "cid": "vehicle***",
        "openModel": 1
    }
}

Message format of returned result

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 25,
    "data": {
        "success": true,
        "msg": "success"
    }
}

Vehicle management

Send a command to add a permanent vehicle

Send a command to add a permanent vehicle. After receiving the command, the vehicle service gateway adds a permanent vehicle and reports the results.

Request parameter

Parameter Type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer When the value of reqType is 5, send a command to add a permanent vehicle. Yes
data Object The business data. Yes
+ id String The unique ID of a specified permanent vehicle. Yes
+ cars Array The list of permanent vehicles. Yes
++ plateNo String The license plate number in the format of A-B0KPTX. Yes
+ beginTime Long The 13-digit timestamp of the start time. Unit: milliseconds. Yes
+ endTime Long The 13-digit timestamp of the end time. Unit: milliseconds. Yes
+ owner String The name of the authorized user. The maximum length is 64 characters. Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 5,
    "data": {
        "id": "12***",
        "cars": [
            {
                "plateNo": "A-B0K123",
            }
        ],
        "beginTime": 1655284422123,
        "endTime": 1655284422123,
        "owner": "James"
    }
}

Response message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 5,
    "data": {
        "success": true,
        "msg": "success",
    }
}

Send a command to modify a permanent vehicle

Send a command to modify the information about a permanent vehicle. After receiving the command, the vehicle service gateway modifies the information about a permanent vehicle and reports the results.

Request parameter

Parameter Type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer When the value of reqType is 6, send a command to modify the information about a permanent vehicle. Yes
data Object The business data. Yes
+ id String The unique ID of a specified permanent vehicle. Yes
+ cars Array The list of permanent vehicles. Yes
++ plateNo String The license plate number in the format of A-B0KPTX. Yes
+ beginTime Long The 13-digit timestamp of the start time. Unit: milliseconds. Yes
+ endTime Long The 13-digit timestamp of the end time. Unit: milliseconds. Yes
+ owner String The name of the authorized user. The maximum length is 64 characters. Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 6,
    "data": {
        "id": "12***",
        "cars": [
            {
                "plateNo": "A-B0K123",
            }
        ],
        "beginTime": 1655284422123,
        "endTime": 1655284422123,
        "owner": "James"
    }
}

Response message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 6,
    "data": {
        "success": true,
        "msg": "success",
    }
}

Send a command to delete a permanent vehicle

Send a command to delete a permanent vehicle. After receiving the command, the vehicle service gateway deletes the specified permanent vehicle and reports the results.

Request parameter

Parameter Type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer When the value of reqType is 7, send a command to delete a permanent vehicle. Yes
data Object The business data. Yes
+ id String The unique ID of a specified permanent vehicle. The maximum length is 64 characters. Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 7,
    "data": {
        "id": "12***"
    }
}

Response message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 7,
    "data": {
        "success": true,
        "msg": "success",
    }
}

Send a command to permit the pass of an unlicensed vehicle

Send a command to permit the pass of an unlicensed vehicle. After receiving the command, the vehicle service gateway permits an unlicensed vehicle to pass the barrier gate and reports the results.

Request parameter

Parameter Type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer When the value of reqType is 8, send a command to permit the pass of an unlicensed vehicle. Yes
data Object The business data. Yes
+ cid String The ID of a specified third-party device. It can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI. The maximum length is 64 characters. Yes
+ cardNo String The ID of an unlicensed vehicle. It can be the user’s unique ID, such as card number, phone number, or WeChat ID. The maximum length is 64 characters. Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 8,
    "data": {
        "cid": "vehicle***",
        "cardNo": "156***",
    }
}

Response message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 8,
    "data": {
        "success": true,
        "msg": "success",
    }
}

Send a command to add a visitor vehicle

Send a command to add a visitor vehicle. After receiving the command, the vehicle service gateway adds a visitor vehicle and reports the results.

Request parameter

Parameter Type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer When the value of reqType is 9, send a command to add a visitor vehicle. Yes
data Object The business data. Yes
+ id String The unique ID of a specified visitor vehicle. The maximum length is 64 characters. Yes
+ plateNo String The license plate number in the format of A-B0KPTX. The maximum length is 64 characters. Yes
+ visitorName String The visitor’s name. The maximum length is 64 characters. Yes
+ visitorPhone String The mobile phone number of the visitor. The maximum length is 64 characters. Yes
+ beginTime Long The 13-digit timestamp of the start time. Unit: milliseconds. Yes
+ endTime Long The 13-digit timestamp of the end time. Unit: milliseconds. Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 9,
    "data": {
        "id": "12***",
        "plateNo": "A-B0K123",
        "visitorName": "visitor",
        "beginTime": 1655284422123,
        "endTime": 1655284422123,
        "visitorPhone": "156***"
    }
}

Response message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 9,
    "data": {
        "success": true,
        "msg": "success",
    }
}

Send a command to modify a visitor vehicle

Request parameter

Parameter Type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer When the value of reqType is 10, send a command to modify a visitor vehicle. Yes
data Object The business data. Yes
+ id String The unique ID of a specified visitor vehicle. The maximum length is 64 characters. Yes
+ plateNo String The license plate number in the format of A-B0KPTX. The maximum length is 64 characters. Yes
+ visitorName String The visitor’s name. The maximum length is 64 characters. Yes
+ visitorPhone String The mobile phone number of the visitor. The maximum length is 64 characters. Yes
+ beginTime Long The 13-digit timestamp of the start time. Unit: milliseconds. Yes
+ endTime Long The 13-digit timestamp of the end time. Unit: milliseconds. Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 10,
    "data": {
        "id": "12***",
        "plateNo": "A-B0K123",
        "visitorName": "visitor",
        "beginTime": 1655284422123,
        "endTime": 1655284422123,
        "visitorPhone": "156***"
    }
}

Response message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 10,
    "data": {
        "success": true,
        "msg": "success",
    }
}

Send a command to delete a visitor vehicle

Request parameter

Parameter Type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer When the value of reqType is 11, send a command to delete a visitor vehicle. Yes
data Object The business data. Yes
+ id String The unique ID of a specified visitor vehicle. The maximum length is 64 characters. Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 11,
    "data": {
        "id": "12***"
    }
}

Response message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 11,
    "data": {
        "success": true,
        "msg": "success",
    }
}

Send a command to extend a visitor vehicle

Send a command to extend the accessible period of a visitor vehicle. After receiving the command, the vehicle service gateway extends the accessible period of the specified visitor vehicle and reports the results.

Request parameter

Parameter Type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer When the value of reqType is 12, send a command to extend the accessible period of a visitor vehicle. Yes
data Object The business data. Yes
+ id String The unique ID of a specified visitor vehicle. The maximum length is 64 characters. Yes
+ beginTime Long The 13-digit timestamp of the start time. Unit: milliseconds. Yes
+ endTime Long The 13-digit timestamp of the end time. Unit: milliseconds. Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 12,
    "data": {
        "id": "12***",
        "beginTime": 1655284422123,
        "endTime": 1655284422123
    }
}

Response message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 12,
    "data": {
        "success": true,
        "msg": "success",
    }
}

Send a command to lock a vehicle

Send a command to lock a vehicle. After receiving the command, the vehicle service gateway locks the specified vehicle and reports the results.

Request parameter

Parameter Type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer When the value of reqType is 15, send a command to lock a vehicle. Yes
data Object The business data. Yes
+ plateNo String The license plate number of the vehicle to be locked, in the format of A-B0KPTX. The maximum length is 64 characters. Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 15,
    "data": {
        "plateNo": "A-B0K123",
    }
}

Response message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 15,
    "data": {
        "success": true,
        "msg": "success",
    }
}

Send a command to unlock a vehicle

Send a command to unlock a vehicle. After receiving the command, the vehicle service gateway unlocks the specified vehicle and reports the results.

Request parameter

Parameter Type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer When the value of reqType is 16, send a command to unlock a vehicle. Yes
data Object The business data. Yes
+ plateNo String The license plate number of the vehicle to be unlocked, in the format of A-B0KPTX. The maximum length is 64 characters. Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 16,
    "data": {
        "plateNo": "A-B0K123",
    }
}

Response message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 16,
    "data": {
        "success": true,
        "msg": "success",
    }
}

Send a command to add a special vehicle

Send a command to add a special vehicle. After receiving the command, the vehicle service gateway adds a special vehicle to the allowlist or blocklist, and reports the results.

Request parameter

Parameter Type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer When the value of reqType is 17, send a command to add a special vehicle. Yes
data Object The business data. Yes
+ plateNo String The license plate number in the format of A-B0KPTX. The maximum length is 64 characters. Yes
+ specialType String The type of a special vehicle. Valid values:
  • WHITE_LIST: Add a vehicle to the allowlist.
  • BLACK_LIST: Add a vehicle to the blocklist.
Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 17,
    "data": {
        "plateNo": "A-B0K123",
        "specialType": "WHITE_LIST"
    }
}

Response message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 17,
    "data": {
        "success": true,
        "msg": "success",
    }
}

Send a command to delete a special vehicle

Send a command to delete a special vehicle. After receiving the command, the vehicle service gateway deletes a special vehicle from the allowlist or blocklist, and reports the results.

Request parameter

Parameter Type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer When the value of reqType is 18, send a command to delete a special vehicle. Yes
data Object The business data. Yes
+ plateNo String The license plate number in the format of A-B0KPTX. The maximum length is 64 characters. Yes
+ specialType String The type of a special vehicle. Valid values:
  • WHITE_LIST: Add a vehicle to the allowlist.
  • BLACK_LIST: Add a vehicle to the blocklist.
Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 18,
    "data": {
        "plateNo": "A-B0K123",
        "specialType": "WHITE_LIST"
    }
}

Response message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 18,
    "data": {
        "success": true,
        "msg": "success",
    }
}

Report a license plate update event

Based on access control records, the working personnel updates the license plate information. The vehicle service gateway reports the updated license plate information. After receiving the information, Tuya IoT Edge Gateway updates the information and returns the results.

Request parameter

Parameter Data type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer A value of 23 indicates a report of the status of a specified device. Yes
data Object The business data. Yes
+ inParkingId String The inbound ID. Yes
+ originalPlateNo String The original license plate number in the format of A-B0KPTX. The maximum length is 64 characters. Yes
+ newPlateNo String The new license plate number in the format of A-B0KPTY. The maximum length is 64 characters. Yes
+ modifyTime Long The 13-digit timestamp of the modification time. Unit: milliseconds. Yes
+ operateId String The ID of a specified operator. The maximum length is 64 characters. No
+ operateName String The name of a specified operator. The maximum length is 64 characters. No

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 19,
    "data": {
        "originalPlateNo": "A-B0K123",
        "newPlateNo": "A-B0K124",
        "modifyTime": 1655284422123,
        "operateId": "***",
        "operateName": "***"
    }
}

Response message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 19,
    "data": {
        "success": true,
        "msg": "success",
    }
}

Order management

Send a command to generate a pending order

Generate an order to be paid for a specified vehicle. After receiving the command, the vehicle service gateway creates the order information and returns the results.

Request parameter

Parameter Type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer When the value of reqType is 13, send a command to generate an order pending payment. Yes
data Object The business data. Yes
+ plateNo String The license plate number in the format of A-B0KPTY. The maximum length is 64 characters. Yes

Response parameter

Parameter Data type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer A value of 13 indicates a response to the command of generating an order pending payment. Yes
data Object The business data. Yes
+ success Bool The returned result.
  • true: success.
  • false: failure.
Yes
+ msg String The response result. The maximum length is 255 characters. Yes
+ plateNo String The license plate number in the format of A-B0KPTX. The maximum length is 64 characters. Yes
+ orderNo String The order ID. The maximum length is 64 characters. Yes
+ inboundTime Integer The 13-digit timestamp of the entry time. Unit: milliseconds. Yes
+ elapsedTime Integer The parking duration. Unit: minutes. Yes
+ startTime Integer The 13-digit timestamp of the time when the billing starts. Unit: milliseconds. Yes
+ payableAmount Integer The payable amount. Unit: cent. Yes
+ paidAmount Integer The actually paid amount. Unit: cent. Yes
+ discountAmount Integer The discount amount. Unit: cent. Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 13,
    "data": {
        "plateNo": "A-B0K123",
    }
}

Message format of returned result

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 13,
    "data": {
        "success": true,
        "msg": "success",
        "plateNo": "A-B0K123",
        "orderNo": "O1234***",
        "inboundTime": 1655284422123,
        "elapsedTime": 66,
        "startTime": 1655284422123,
        "payableAmount": 2000,
        "paidAmount": 600,
        "discountAmount": 1400
    }
}

Send a command to notify the vehicle service gateway of payment results

After the order payment is successful, send a command to notify the vehicle service gateway of the payment result. After receiving the command, the vehicle service gateway performs the operation and returns the results.

Request parameter

Parameter Type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer When the value of reqType is 14, send a command to notify the vehicle service gateway of the payment result. Yes
data Object The business data. Yes
+ orderNo String The order ID. The maximum length is 64 characters. Yes
+ paidAmount Integer The paid amount. Unit: cent. Yes
+ payMethod Integer The payment method. Valid values:
  • 1: Alipay
  • 2: WeChat
  • 3: bank card
  • 4: cash
  • 5: others
Yes
+ payTime Long The 13-digit timestamp of the payment time. Unit: milliseconds. Yes
+ payerMobile String The mobile phone number of the payer. The maximum length is 64 characters. No
+ payerName String The name of the payer. The maximum length is 64 characters. No

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 14,
    "data": {
        "orderNo": "O1234***",
        "paidAmount": 600,
        "payMethod": 1,
        "payTime": 1655284422123,
        "payerMobile": "156***",
        "payerName": "James",
    }
}

Message format of returned result

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 14,
    "data": {
        "success": true,
        "msg": "success"
    }
}

Data management

Send a command to synchronize data

Send a command to synchronize the data. After receiving the command, the vehicle service gateway asynchronously reports the payment record or access control record based on the data synchronization type and parameters and returns the results.

Reporting rules:

  • Synchronize the data within a specified time period.
  • If the data in the time period is inconsistent with the total number of data in the cloud, it will be reported. If they are consistent, it does not need to be reported.

Request parameter

Parameter Type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer When the value of reqType is 20, send a command to synchronize the data. Yes
data Object The business data. Yes
+ dataType Integer The type of data to be synchronized. Valid values:
  • 1: the access control data.
  • 2: the payment record data.
Yes
+ plateNo String The license plate number in the format of A-B0KPTX. The maximum length is 64 characters. Yes
+ syncDataParams Array Data synchronization parameter. Yes
++ totalCount Integer The total number of records within a specified time period. Yes
++ startTime Long The 13-digit timestamp of the start time. Unit: milliseconds. Yes
++ endTime Long The 13-digit timestamp of the end time. Unit: milliseconds. Yes
++ passDirection Integer The type of access control. Valid values:
  • 1: enter.
  • 2: exit. This type of records is required to be reported.
Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 20,
    "data": {
        "dataType": 1,
        "syncDataParams": [
            {
                "totalCount": 100,
                "startTime": 1655284422123,
                "endTime": 1655284422123,
                "passDirection": 1
            }
        ]
    }
}

Response message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 20,
    "data": {
        "success": true,
        "msg": "success",
    }
}

Report a payment event

The vehicle service gateway reports the data of payment events proactively or after receiving the data synchronizing command.

Request parameter

Parameter Data type Description Required
t Long The time when a push notification is sent. Yes
reqId String The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer A value of 21 indicates a report of payment events. Yes
data Object The business data. Yes
+ records Array The list of payment events. Yes
++ plateNo String The license plate number in the format of A-B0KPTX. The maximum length is 64 characters. Yes
++ orderNo String The ID of a specified order. The maximum length is 64 characters. Yes
++ startTime Long The 13-digit timestamp of the time when the billing starts. Unit: milliseconds. Yes
++ endTime Integer The 13-digit timestamp of the time when the billing ends. Unit: milliseconds. Yes
++ payMethod Integer The payment method. Valid values:
  • 1: Alipay
  • 2: WeChat Pay
  • 3: bank card
  • 4: cash
  • 5: others
Yes
++ payTime Long The 13-digit timestamp of the payment time. Unit: milliseconds. Yes
++ payableAmount Integer The payable amount. Unit: cent. Yes
++ paidAmount Integer The actually paid amount. Unit: cent. Yes
++ discountAmount Integer The discount amount. Unit: cent. Yes
++ inParkingId String The entry ID. The maximum length is 64 characters. Yes
++ voucherType Integer The payment voucher.
  • 1: license plate number
  • 2: parking space
  • 3: unlicensed vehicle
  • 4: card
  • 99: others
Yes
++ voucherDesc String The description of a payment voucher, which can be the license plate number or card number or others. Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 21,
    "data": {
        "records": [
            {
                "plateNo": "A-B0K123",
                "orderNo": "O1234***",
                "startTime": 1655284422123,
                "endTime": 1655284422123,
                "paidAmount": 600,
                "payMethod": 1,
                "payTime": 1655284422123,
                "payableAmount": 2000,
                "discountAmount": 1400,
                "inParkingId": "park***"
                "voucherType": 1,
                "voucherDesc": "A-B0K123"
            }
        ]
    }
}

Response message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 21,
    "data": {
        "success": true,
        "msg": "success",
    }
}

Report an access event

The vehicle service gateway reports the data of access events proactively or after receiving the data sync command.

Request parameter

Parameter Data type Description Required
t Long The time when a push notification is sent. Yes
reqId String The identifier of a specified request. We recommend that the request identifier be generated by the UUID. The gateway can listen for the returned result based on reqId. The maximum length is 64 characters. Yes
reqType Integer A value of 22 indicates a report of access events. Yes
data Object The business data. Yes
+ records Array The list of access events. Yes
++ cid String The ID of a specified third-party device. Yes
++ plateNo String The license plate number in the format of A-B0KPTX. The maximum length is 64 characters. Yes
++ passDirection Integer The type of access control. Valid values:
  • 1: enter the parking lot.
  • 2: exit the parking lot.
Yes
++ passTime Integer The 13-digit timestamp of the access time. Unit: milliseconds. Yes
++ openState Integer The working status of a specified barrier gate. Valid values:
  • 1: normal
  • 2: anomaly
  • 3: unknown
Yes
++ imageUrl String The URL of a specified image. For example, http://xxx.jpg. The maximum length is 255 characters. The URL shall support access and download. Yes
++ inParkingId String The inbound ID. The maximum length is 64 characters. Yes
++ operateId String The ID of a specified operator. The maximum length is 64 characters. No
++ operateName String The name of a specified operator. The maximum length is 64 characters. No
++ plateDimension Integer The type of a specified vehicle. Valid values:
  • 1: vehicle of temporary parking
  • 2: unlicensed vehicle
  • 3: vehicle of monthly payment
  • 4: vehicle in the allowlist
  • 5: internal vehicle
  • 6: vehicle with purchased parking space
  • 99: other vehicles
Yes
++ feeDimension Integer The payment type. Valid values:
  • 1: paid
  • 2: free
Yes
++ passDimension Integer The type of access control. Valid values:
  • 1: manual control
  • 2: remote control
  • 3: automatic control
  • 4: anomaly
Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 22,
    "data": {
        "records": [
            {
                "cid": "vehicle***",
                "plateNo": "A-B0K123",
                "passDirection": 1,
                "passTime": 1655284422123,
                "openState": 1,
                "imageUrl": "http://***.jpg",
                "inParkingId": "***",
                "operateId": "***",
                "operateName": "***",
                "plateDimension": 1,
                "feeDimension": 1,
                "passDimension": 3
            }
        ]
    }
}

Response message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 22,
    "data": {
        "success": true,
        "msg": "success",
    }
}

Sample application

MQTT connection example:


import (
	"crypto/md5"
	"encoding/hex"
	"fmt"
	"log"
	"time"

		mqtt "github.com/eclipse/paho.mqtt.golang"
)

var (
	client mqtt.Client
	pubTopic string
	subTopic string
	password string
)

func main() {
	log.SetFlags(log.LstdFlags | log.Lshortfile)

		var (
			username = "tuya_vehicle_***"
			clientId = "vehicle_*"
			broker   = "tcp://ip:port"
	)
	password = string(genSecKey(clientId, username))
	pubTopic = fmt.Sprintf("gateway/vehicle/out/%s", clientId)
	subTopic = fmt.Sprintf("gateway/vehicle/in/%s", clientId)

	opts := mqtt.NewClientOptions().SetClientID(clientId).SetUsername(username).SetPassword(password)
	opts = opts.SetAutoReconnect(true).SetCleanSession(true).SetKeepAlive(5 * time.Second).
			SetMaxReconnectInterval(10 * time.Second).
			SetConnectRetry(true).SetConnectRetryInterval(time.Second)

	opts.AddBroker(broker)
	opts.SetOnConnectHandler(func(client mqtt.Client) {
			log.Println("connected")

			client.Subscribe(subTopic, 1, onMessage)
	}).SetConnectionLostHandler(func(client mqtt.Client, err error) {
			log.Println("connect lost")
	})
	client = mqtt.NewClient(opts)
	token := client.Connect()
	if ok := token.WaitTimeout(time.Second * 10); ! ok {
		panic("connect timeout")
	}

	for {
	}
}

func onMessage(client mqtt.Client, msg mqtt.Message) {
	log.Printf("onmessage, topic:%v, messageId:%v, msg: %+v\n", msg.Topic(), msg.MessageID(), string(msg.Payload()))
	// Message processing logic
}

// publish Send messages
func publish(payload []byte) error {
	token := client.Publish(pubTopic, 1, true, payload)
	log.Println(token)
	return nil
}

func genSecKey(clientID, userName string) []byte {
	secKey := genMd5(clientID + userName)[:16]
	return []byte(secKey)
}

func genMd5(source string) (md5str string) {
	md5Ctx := md5.New()
	md5Ctx.Write([]byte(source))
	cipherStr := md5Ctx.Sum(nil)
	md5str = hex.EncodeToString(cipherStr)
	return
}