# 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

Topic	Description
shadow/${shadow_id}	Topic for publishing. It's unique, for publishing messages from the device or the client to the service.
shadow/${shadow_id}/reply	Topic 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.

Method	Description
PUT	Use 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.
PATCH	Use 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.
GET	Use 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

Key	Type	Description
data	Object	Message payload published through topic or API call.
createAt	Number	Created time
lastTime	Number	Last updated time
version	Number	How 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.

← Features API Overview →