# Communication

# MQTT

The device's messages communicate between the device and the broker by topics, which is no different from regular topic communication, but with the additional storage (data cache) capability. The device or the application can communicate through two topics: the topic for publishing and the topic for subscription.

# Topics and Methods

TopicDescription
shadow/${shadow_id}Topic for publishing. It's unique, for publishing messages from the device or the client to the service.
shadow/${shadow_id}/replyTopic for subscription. It's unique, for the device or the client subscribing messages from the service.

In addition to the payload, the message should also define the method that tells the service how the message should be updated.

MethodDescription
PUTUse this method in the topic for publishing. Corresponding to the PUT method of HTTP, the method is for updating the specified shadow model’s JSON entirely. See invocation examples below.
PATCHUse this method in the topic for publishing. Corresponding to the PATCH method of HTTP, the method is for updating the specified shadow model’s JSON partially. See invocation examples below.
GETUse this method in the topic for publishing. Corresponding to the GET method of HTTP, the method is for getting the specified shadow model’s JSON. See invocation examples below.

In the case of updating a payload using the PATCH method, it can't add new multi-level objects at once. See invocation examples below.

# Shadow Model JSON

{
    "data": {},
    "createAt": 1660201961567,
    "lastTime": 1660204233317,
    "version": 3
}
1
2
3
4
5
6
KeyTypeDescription
dataObjectMessage payload published through topic or API call.
createAtNumberCreated time
lastTimeNumberLast updated time
versionNumberHow many times the JSON payload has been updated.

# Invocation Examples

# Entire Update

Update the specified shadow model’s JSON entirely by PUT.

Original shadow model’s JSON

{
    "Key01": {
        "a": 100
    }
}
1
2
3
4
5

Entire update through topic (shadow/${shadow_id})

{
    "method": "PUT",
    "payload": {
        "Key01": {
            "b": 200,
            "c": 300
        },
        "Key02": {
            "d" : 400
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12

Shadow model’s JSON updated result

{
    "Key01": {
        "b": 200,
        "c": 300
    },
    "Key02": {
        "d": 400
    }
}
1
2
3
4
5
6
7
8
9

# Partial Update

Update the specified shadow model’s JSON partially by PATCH.

Original Shadow model’s JSON

{
    "Key01": {
        "a": 100
    }
}
1
2
3
4
5

Partial update through topic (shadow/${shadow_id})

{
    "method": "PATCH",
    "payload": {
        "Key01": {
            "b": 200,
            "c": 300
        }
    }
}
1
2
3
4
5
6
7
8
9

Shadow model’s JSON updated result

{
    "Key01": {
        "a": 100,
        "b": 200,
        "c": 300
    }
}
1
2
3
4
5
6
7

# Add new multi-level objects

Because it can't add new multi-level objects at once by partial update, the object should be added one level at a time.

Shadow model’s JSON

{
    "Key01": {
        "a": 100
    }
}
1
2
3
4
5

The following ways of directly adding multi-level objects will report errors

{
    "method": "PATCH",
    "payload": {
        "Key01": {
            "a": 100
        },
        "Key02": {
            "b": 200
        }
    }
}

{
    "method": "PATCH",
    "payload": {
        "Key01": {
            "a": 100,
            "Key02": {
                "b": 200
            }
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

Create new multi-level object level by level.

First Step

{
    "method": "PATCH",
    "payload": {
        "Key01": {
            "a": 100
        },
        "Key02": {}
    }
}
1
2
3
4
5
6
7
8
9

Second Step

{
    "method": "PATCH",
    "payload": {
        "Key01": {
            "a": 100
        },
        "Key02": {
            "b": 200
        }
    } 
}
1
2
3
4
5
6
7
8
9
10
11

# Get shadow model’s JSON

Get shadow model’s JSON by GET

Shadow model’s JSON

{
    "Key01": {
        "a": 100
    },
    "Key02": {
        "b": 200
    }
}
1
2
3
4
5
6
7
8

Get the shadow model’s JSON through the topic (shadow/${shadow_id})

{
    "payload": {},
    "method": "GET"
}
1
2
3
4

Receive the message through the topic for subscription (shadow/${shadow_id}/reply)

{
    "data": {
        "Key01": {
            "a": 100
        },
        "Key02": {
            "b": 200
        }
    },
    "createAt": 1660201961567,
    "lastTime": 1660204233317,
    "version": 2
}
1
2
3
4
5
6
7
8
9
10
11
12
13

# API Communication

EMQX Cloud provides APIs to get details from shadow services.

Please see the API - Shadow Services to learn more.

What’s on this page