draft for repivoting to IoT Central #178
Conversation
| 1. Once the application has been provisioned, you will automatically be redirected to the new application dashboard. | ||
|
|
||
| To register a device: | ||
| **TODO** Add a screenshot. Also if they already have a free instance, we might need to direct them to use that instead, or deploy a paid instance which required an Azure subscription |
There was a problem hiding this comment.
Suggest adding a single screenshot, BEFORE submitting, that shows the results of the selections you told user to make in previous steps. As an example, see the screen in step (4) of this IoT Central quickstart:
| ### Create the IoT Central Application | ||
|
|
||
| ### Register a device | ||
| Azure IoT Central is used to both manage and interact with your device. |
There was a problem hiding this comment.
Here, in a 'quickstart' type doc we wouldn't need to get TOO descriptive, but we definitely need to add a concise sentence or two explaining the major "happy path" options we offer for developers to hook up a device to IoT. As in: (1) Roll your own (using CLI, create a device, etc., as we do in the IoT Hub and our new Python quickstart), or (2) Use Central's portal. Concisely indicate "why" in this instance, we're using Central.
And this is just a thought, doesn't impact the text in the doc here, but: Have we confirmed with the device dev leadership that for these devices, this is the "happy path" we want to show folks for their first time to connect a device? Are we convinced this is how many/most of them will prefer to work? I'm not saying we shouldn't do this, just asking because I don't know.
There was a problem hiding this comment.
Agree, Central should be just an option. Central mean cost or a very short test period (1 week), it is not a free offer as Azure /Hub. I suggest to add a note and a link to a paragraph (at the end of this article?) on how to use central and let the 'traditionally' way.
|
|
||
| > Note: The setup script installs the following tools: | ||
| > * [GCC](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm): Compile | ||
| > Note: The setup script installs the following tools used in this guide: |
There was a problem hiding this comment.
Keep this to original: > Note: The setup script installs the following tools
...try to avoid adding extra baggage about the 'guide'. Why? Because 'guide' is not actually a Microsoft doctype, really a quickstart here, and more lengthy docs would be tutorial. When we move this content to docs.ms.com, if we have scattered references to non doctypes in a lot of places like 'guide', the validation will throw all kinds of exceptions. We can do this here in the repo, but actually just trying to be consistent with our doc model AND save you validation cleanup later when we migrate these.
| ### Create the IoT Central Application | ||
|
|
||
| ### Register a device | ||
| Azure IoT Central is used to both manage and interact with your device. |
There was a problem hiding this comment.
...."manage and monitor your device" ??
To be consistent with the IoT Central docs messaging about the purpose of Central (see here: https://docs.microsoft.com/en-us/azure/iot-central/core/overview-iot-central), the high-level tasks are Create/Manage/Monitor/Troubleshoot.
So in this doc, to be consistent with Central, ideally we should talk in terms of the Create/Manage/Monitor messaging.
| 1. Add an application and a URL. | ||
| 1. Choose the "Free" Pricing plan to activate a 7-day trial. | ||
| 1. Click "Create". | ||
| 1. Once the application has been provisioned, you will automatically be redirected to the new application dashboard. |
There was a problem hiding this comment.
"After" the application has been provisioned....
After will localize easier than 'once'.
| 1. Add an application and a URL. | ||
| 1. Choose the "Free" Pricing plan to activate a 7-day trial. | ||
| 1. Click "Create". | ||
| 1. Once the application has been provisioned, you will automatically be redirected to the new application dashboard. |
There was a problem hiding this comment.
Switch to active voice:
After IoT Central provisions the application, it redirects you automatically to the new application dashboard.
| ### Create a new device | ||
|
|
||
| *YourIotHubName*. Replace this placeholder below with the name you chose for your IoT hub. | ||
| In this section, you create a new device via the IoT Central application dashboard provisioned in the previous steps. You will use the connection information for the newly created device to securely connect your physical device in a later section. |
There was a problem hiding this comment.
In this section, you use the IoT Central application dashboard to create a new device.
| 1. Start "+ New" to bring up the "Create a new device" window. | ||
| 1. Leave Device template as "Unassigned". | ||
| 1. Fill in the desired Device Name and Device ID. | ||
| 1. Select the "Create" button. |
There was a problem hiding this comment.
As above, I'd add a confirming screen shot here showing the result of the previous choices, before user submits.
| ## Prepare the device | ||
|
|
||
| Confirm that you have the copied the following values from the JSON output from the previous sections: | ||
| Confirm that you have the noted the connection information from the Azure IoT Central portal from the previous section: |
There was a problem hiding this comment.
Note the connection values for the following connection string parameters displayed in the IoT Central portal. You'll add these values to a configuration file in the next step.
|  | ||
| 1. Change **Payload** to *false*, and again select **Invoke method**. The LED light should turn off. | ||
| 1. Optionally, you can view the output in Termite to monitor the status of the methods. | ||
| You can also use Azure IoT Central to call a direct method that you have implemented on your device. Direct methods have a name, and can optionally have a JSON payload, configurable connection, and method timeout. In this section, you call a method that enables you to turn an LED on or off. |
There was a problem hiding this comment.
"You can also use IoT Central...."
After we've stated the branded service "Azure IoT Central" once near the start of article, subsequently we can just shorten to "IoT Central" throughout the article in all cases except when we actually WANT the full branded name.
| ## Clean up resources | ||
| If you no longer need the Azure resources created in this tutorial, you can use the Azure CLI to delete the resource group and all the resources you created for this tutorial. Optionally, you can use Azure IoT Explorer to delete individual resources including devices and IoT hubs. | ||
| If you no longer need the Azure resources created in this tutorial, you can delete them from the Azure IoT Central portal. |
There was a problem hiding this comment.
Should we show them briefly how to delete? In other quickstarts on services, we always give the actual CLI or portal actions to cleanup if user wants. And as you did here, point out that some of the resources, like the app and possibly the device, could be reused in other docs.
timlt
left a comment
timlt
left a comment
There was a problem hiding this comment.
Overall I'm good with the Central approach, as an alternative to the CLI-based approach. But see my comments inline, just thoughts on that. I do think we need to concisely mention the CLI option, and state the 'why' of using Central here.
timlt
left a comment
timlt
left a comment
There was a problem hiding this comment.
The screen updates and some text fixes look good. The things that still jump out are...
- In opening para of article, need to remove the bullets about using CLI and IoT Explorer, replace with a single bullet about using Central for those tasks.
- In the section that introduces the use of Central to create the application, see my comments there. We still need an introduction sentence describing concisely, what are the OPTIONS for a user to manage their hub and app (basically: programmatically, with CLI, or with Central), and then what IS Central (see the landing page or overview article to the Central service for some handy summary text that you can reuse). So basically, just need to add maybe 2 short sentence at the start of this section saying there's a few ways you could manage/monitor your app, but here we're using Central because.....convenience.
- Some TODO's still to address in body of article.
- I thought the comment AFTER the first screen from Central was confusing, you COULD have used a standard app, etc. I think we could just condense all that down to something like: if you have an existing IoT Central application, you can use it complete the steps in this article rather than create a new application.
| ### Create the IoT Central Application | ||
|
|
||
| Azure IoT Central is used to both manage and monitor with your device. | ||
| There are a few ways to mange and monitor your devices. Azure IoT Central is used here because it provide the easiest way to connects your IoT devices to the cloud and offers centralized management to reconfigure and update your devices. |
There was a problem hiding this comment.
How about something like this for opening para?
There are several ways to connect devices to Azure IoT. In this section, you learn how to connect a device by using Azure IoT Central. IoT central is an IoT application platform that reduces the cost and complexity of creating and managing IoT solutions.
|
|
||
|  | ||
|
|
||
| 1. Click "Create". |
There was a problem hiding this comment.
This is a general tip, I will just make it here at the start and if you choose to, you can update it throughout article, including a couple of the previous steps as well as the following content. First, instead of using "click" anywhere always use "select." You would've had no way of knowing this, but this has to do with localization and while these docs here will not be localized, eventually we plan to migrate these to docs repo so it helps to follow that standard now. Second item, instead of surrounding named UI items in the portal with quotes like "Create" for the create button, it is conventional to bold the UI items. So, here are suggested changes for step 1, and if you follow thru on this, can quickly make these same changes throughout article where appropriate.
- Select Create.
| 1. Click "Connect" in the top right menu bar to show the connection information for use in the physical device in the next section. | ||
|
|
||
| **TODO** instruct the user to capture the required connection information. Given that this is used immediately in the next section, perhaps displaying the connection information should be directly part of the next section so the customer can just copy the information straight from central. We also should have a screenshot of the connection information screen. | ||
|  |
There was a problem hiding this comment.
Putting the 3 items to note in the NEXT section, to me, is a little confusing. Instead, I'd move the bit about "Note the connection values..." and the 3 bullet point items, up into the previous section as another step AFTER they've open the 'connect' info view. So if the previous step was (7) to open the connect info, maybe you have a new step (8) in previous section that has all this info and begins something like this (include your same 3 bullets below):
- Note the following connection string parameters displayed in the Connect dialog. You'll add these values to a configuration file in the next step.
[Then your existing 3 bullets would go here]
And then continue with the content you have below....
Prepare the device
To connect the STM DevKit to Azure.....
And then another comment in the ##Add Configuration section. When we say "open the following file in a text editor", I'm just confirming: Is this file path going to be identical regardless which of the two possible STM boards and articles the user may be working on? Because it looks like we have the exact same file path to this file in both articles for the two STM boards. Just confirming that it SHOULD be the same path.
Finally, we have this sentence when they build the image: "After the build completes, confirm that two binary files were created. There's a binary image for each of the STM Devkit. The build saves the images to the following paths:". We should simplify that paragraph to something like:
After the build completes, confirm that it created two binary files in the following paths:
ryanwinter
left a comment
ryanwinter
left a comment
There was a problem hiding this comment.
Remove reference to requireing an Azure subscription. You can use the free subscription in Central without a subscription
| 1. Run the [az iot hub create](https://docs.microsoft.com/cli/azure/iot/hub?view=azure-cli-latest#az-iot-hub-create) command to create an IoT hub. It might take a few minutes to create an IoT hub. | ||
| To create a new application: | ||
| 1. From [Azure IoT Central portal](https://apps.azureiotcentral.com/), click "My apps" on the side navigation menu. | ||
| 1. Start "+ New application". |
There was a problem hiding this comment.
Replace Start with Select
| 1. From [Azure IoT Central portal](https://apps.azureiotcentral.com/), click "My apps" on the side navigation menu. | ||
| 1. Start "+ New application". | ||
| 1. Select "Custom apps". | ||
| 1. Add an application and a URL. |
There was a problem hiding this comment.
application = Application Name
| ## View device properties | ||
| > **Note**: Check the device's "Device template" is updated. If unassigned, select the device and "Migrate" to the "Getting Started Guide" template in order to see the graphic visual data representation. |
There was a problem hiding this comment.
This part could confuse some people. I know what you're getting at--user needs to go back into Central portal and check something. I think we need to just give them a simple step or two, making it clear to look back into the portal and what to check. Also a screen shot showing what they're looking for would be helpful.
| 1. After IoT Central provisions the application, it redirects you automatically to the new application dashboard. | ||
|
|
||
| 1. After the IoT hub is created, view the JSON output in the console, and copy the `hostName` value to use in a later step. The `hostName` value looks like the following example: | ||
| If you have an existing IoT Central application, you can use it to complete the steps in this article rather than create a new application. |
There was a problem hiding this comment.
Make this a Note to show it as an optional step.
There was a problem hiding this comment.
Do you mean just add a Note tag?
| 1. Fill in the desired Device Name and Device ID. | ||
|
|
||
| To register a device: | ||
|  |
There was a problem hiding this comment.
This screenshot is huge, would it make sense to crop this to just the "Create a new device" window?
|
|
||
| 1. In your console, run the [az iot hub device-identity create](https://docs.microsoft.com/cli/azure/ext/azure-cli-iot-ext/iot/hub/device-identity?view=azure-cli-latest#ext-azure-cli-iot-ext-az-iot-hub-device-identity-create) command. This creates the simulated device identity. | ||
| 1. Select the "Create" button. | ||
| 1. The newly created device should appear in the "All devices" list. Click on the device name to show details. |
There was a problem hiding this comment.
replace "should" with "will"
| ``` | ||
|
|
||
| 1. After the device is created, view the JSON output in the console, and copy the `deviceId` and `primaryKey` values to use in a later step. | ||
|  |
There was a problem hiding this comment.
Crop to the "device connection" window
| 1. In your console, run the [az iot hub device-identity create](https://docs.microsoft.com/cli/azure/ext/azure-cli-iot-ext/iot/hub/device-identity?view=azure-cli-latest#ext-azure-cli-iot-ext-az-iot-hub-device-identity-create) command. This creates the simulated device identity. | ||
| 1. Select the "Create" button. | ||
| 1. The newly created device should appear in the "All devices" list. Click on the device name to show details. | ||
| 1. Click "Connect" in the top right menu bar to show the connection information for use in the physical device in the next section. |
There was a problem hiding this comment.
Reword:
- Click "Connect" in the top right menu bar to display the connection information used to configure the device in the next section.
| 1. Click "Connect" in the top right menu bar to show the connection information for use in the physical device in the next section. | ||
|
|
||
| **TODO** instruct the user to capture the required connection information. Given that this is used immediately in the next section, perhaps displaying the connection information should be directly part of the next section so the customer can just copy the information straight from central. We also should have a screenshot of the connection information screen. | ||
|  |
| ``` | ||
| 1. Inspect the properties for your device in the console output. | ||
| > **Note**: Check the device's "Device template" is updated. If unassigned, select the device and "Migrate" to the "Getting Started Guide" template in order to see the graphic visual data representation. |
There was a problem hiding this comment.
This is a workaround for the Central bug, but there is nothing here about viewing device properties, maybe the heading should be "verify the device status", and in there would be to make sure the "device status" changes provisioned, and that the "device template" is correctly migrated (or migrate manually if not).
|
|
||
| You can view the device information from IoT Central. | ||
|
|
||
| 1. Select **About** tab from the device page. |
There was a problem hiding this comment.
In an H2 section like this where we only have a single step (not a sequence of steps), then there's no need to number them. Can just remove the OL item number and 'outdent' the text and image to the left margin.
|
|
||
| 1. Select **About** tab from the device page. | ||
|
|
||
|  |
There was a problem hiding this comment.
Ideally, we'd show HOW to delete/cleanup from the portal. But if we think that is simple enough and clear enough to do in the UI without specific "Select Delete" type of instructions (and it probably is), then we should at least give a little more explicit directions here on WHICH resources to remove/delete.
For example, maybe wording something like this:
If you no longer need the Azure resources created in this tutorial, you can delete them from the IoT Central portal. Optionally, if you continue to another tutorial in this Getting Started guide, you can keep the resources you've already created and reuse them.
To keep the sample application but remove only specific devices:
- Select the Devices tab for your application.
- Select a device.
- Select the ... button from the device commands menu, and then select Delete.
To remove an entire sample application and all its devices and resources:
- Select Administration > Your application.
- Select Delete.
timlt
left a comment
timlt
left a comment
There was a problem hiding this comment.
OK Jasmine, updated comments submitted. I think if you implement these should be good to go!
jasmineymlo
force-pushed
the
jasminel/wip
branch
from
c690582 to
8fd2004
Compare
| > *getting-started\STMicroelectronics\STM32L4_L4+\tools\rebuild.bat* | ||
|
|
||
| After the build completes, confirm that two binary files were created. There's a binary image for each version of the STM Devkit. The build saves the images to the following paths: | ||
| After the build completes, confirm that two binary files were created. There's a binary image for each of the STM Devkit. The build saves the images to the following paths: |
There was a problem hiding this comment.
Would suggest simplifying this down to something like:
After the build completes, confirm that two binary files were created in the following paths. There's one binary each for each STM Devkit device.
| To view the device status in IoT Central portal: | ||
| 1. From the application dashboard, select **Devices** on the side navigation menu. | ||
| 1. Check the **Device status** of the device is updated to **Provisioned**. | ||
| 1. Check the **Device template** of the device is updated to **Getting Stared Guid**. |
There was a problem hiding this comment.
See a typo, should be:
...updated to Getting Started Guide.
| > Note: If the **Device template** of the device remains as **Unassigned**, select the device and select **Migrate** to the "Getting Started Guide" template in order to see the graphic visual data representation. | ||
| 1. Inspect the properties for your device in the console output. | ||
|  |
There was a problem hiding this comment.
Looks like image link may not be working here?
jasmineymlo
force-pushed
the
jasminel/wip
branch
from
e7cad39 to
e1c7303
Compare
Please review this draft version. Feel free to modify on the branch if needed. Thanks.