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 ​

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

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
}

Invocation Examples ​

Entire Update ​

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

Original shadow model’s JSON

{
    "Key01": {
        "a": 100
    }
}

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

{
    "method": "PUT",
    "payload": {
        "Key01": {
            "b": 200,
            "c": 300
        },
        "Key02": {
            "d" : 400
        }
    }
}

Shadow model’s JSON updated result

{
    "Key01": {
        "b": 200,
        "c": 300
    },
    "Key02": {
        "d": 400
    }
}

Partial Update ​

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

Original Shadow model’s JSON

{
    "Key01": {
        "a": 100
    }
}

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

{
    "method": "PATCH",
    "payload": {
        "Key01": {
            "b": 200,
            "c": 300
        }
    }
}

Shadow model’s JSON updated result

{
    "Key01": {
        "a": 100,
        "b": 200,
        "c": 300
    }
}

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
    }
}

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
            }
        }
    }
}

Create new multi-level object level by level.

First Step

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

Second Step

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

Get shadow model’s JSON ​

Get shadow model’s JSON by GET

Shadow model’s JSON

{
    "Key01": {
        "a": 100
    },
    "Key02": {
        "b": 200
    }
}

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

{
    "payload": {},
    "method": "GET"
}

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
}

API Communication ​

EMQX Cloud provides APIs to get details from shadow services.

Please see the API - Shadow Services to learn more.