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.

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

Business process

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
}

Prev DocEnvironmental Monitoring Device

Next DocPerimeter Device