Revamp IoT docs

content/en/user-guide/aws/elastic-compute-cloud/index.md

@@ -169,7 +169,7 @@ Once the instance is up and running, we can use the `ssh` command to set up an S
 {{< command >}}
 $ ssh -p 12862 -i key.pem [email protected]
 {{< /command >}}
-{{< alert title="Hint" color="info">}}
+{{< alert title="Hint" color="success">}}
 If the `ssh` command throws an error like "Identity file not accessible" or "bad permissions", then please make sure that the key file has a restrictive `0400` permission as illustrated [here](#create-a-key-pair).
 {{< /alert >}}
 ## Docker backend

content/en/user-guide/aws/iot/index.md

@@ -8,12 +8,21 @@ aliases:
   - /aws/iot/
 ---
 
-LocalStack Pro supports IoT Core, IoT Data, IoT Analytics and related APIs.
+## Introduction
+
+AWS IoT provides cloud services to manage IoT fleet and integrate them with other AWS services 
+
+LocalStack Pro supports IoT Core, IoT Data, IoT Analytics and related APIs as well as an in-built MQTT broker.
 Common operations for creating and updating things, groups, policies, certificates and other entities are implemented with full CloudFormation support.
+The supported APIs are available on our [API coverage page](https://docs.localstack.cloud/references/coverage/coverage_iot/).
+
+## Getting Started
 
-## MQTT Broker
+This guide is for users that are new to IoT and assumes a basic knowledge of the AWS CLI and LocalStack [`awslocal`](https://github.com/localstack/awscli-local) wrapper.
 
-LocalStack ships with a built-in MQTT broker.
+Start LocalStack using your preferred method.
+
+LocalStack ships an MQTT (Message Queuing Telemetry Transport) broker powered by [Mosquitto](https://mosquitto.org/) which supports both pure MQTT and MQTT-over-WSS (WebSockets Secure) protocols.
 To retrieve the MQTT endpoint, use the [`DescribeEndpoint`](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeEndpoint.html) operation.
 
 {{< command >}}
@@ -23,17 +32,47 @@ $ awslocal iot describe-endpoint
 }
 {{< / command >}}
 
-This endpoint can then be used with any MQTT client to publish and subscribe to topics.
-
 {{< alert title="Hint" color="success" >}}
 LocalStack lazy-loads services by default.
 The MQTT broker may not be automatically available on a fresh launch of LocalStack.
-You should make a `DescribeEndpoint` call to ensure the broker is running.
+You should make a `DescribeEndpoint` call to ensure the broker is running and identify the port.
 {{< /alert >}}
 
+This endpoint can then be used with any MQTT client to publish and subscribe to topics.
+In this example, we will use the [Hive MQTT CLI](https://hivemq.github.io/mqtt-cli/docs/installation/).
+
+Run the following command to subscribe to an MQTT topic.
+
+{{< command >}}
+$ mqtt subscribe \
+        --host localhost.localstack.cloud \
+        --port 4510 \
+        --topic climate
+{{< /command >}}
+
+In another terminal, publish a message to this topic.
+
+{{< command >}}
+$ mqtt publish \
+        --host localhost.localstack.cloud \
+        --port 4511 \
+        --topic climate \
+        -m "temperature=30°C;humidity=60%"
+{{< /command >}}
+
+This message will be pushed to all subscribers of this topic, including the one in the first terminal.
+
+## Using Authentication
+
+LocalStack IoT maintains its own root certificate authority which is refreshed at every run.
+The root CA certificate can be retrieved from the internal endpoint `/_aws/iot/LocalStackIoTRootCA.pem`.
+
+When using the AWS IoT SDKs
+
+
 ## Lifecycle Events
 
-LocalStack also publishes the [lifecycle events](https://docs.aws.amazon.com/iot/latest/developerguide/life-cycle-events.html) to the standard endpoints.
+LocalStack publishes the [lifecycle events](https://docs.aws.amazon.com/iot/latest/developerguide/life-cycle-events.html) to the standard endpoints.
 
 - `$aws/events/presence/connected/clientId`: when a client connects
 - `$aws/events/presence/disconnected/clientId`: when a client disconnects
@@ -47,14 +86,14 @@ Currently the `principalIdentifier` and `sessionIdentifier` fields in event payl
 LocalStack can publish the [registry events](https://docs.aws.amazon.com/iot/latest/developerguide/registry-events.html), if [you enable it](https://docs.aws.amazon.com/iot/latest/developerguide/iot-events.html#iot-events-enable).
 
 {{< command >}}
-$ awslocal iot update-event-configurations --event-configurations "{\"THING\":{\"Enabled\": true}}"
+$ awslocal iot update-event-configurations --event-configurations '{"THING":{"Enabled": true}}'
 {{< / command >}}
 
 You can then subscribe or use topic rules on the follow topics:
 
-- `$aws/events/thing/<thingName>/created`: when a new Thing is created
-- `$aws/events/thing/<thingName>/updated`: when a Thing is updated
-- `$aws/events/thing/<thingName>/deleted`: when a Thing is deleted
+- `$aws/events/thing/<thingName>/created`: when a new thing is created
+- `$aws/events/thing/<thingName>/updated`: when a thing is updated
+- `$aws/events/thing/<thingName>/deleted`: when a thing is deleted
 
 ## Topic Rules