Better documentation for C and Device Management features [enhancement]

[rangedsp]

I am working on quite a few projects from different companies looking to implement IoT Hub with device management, using C.

A few problems/suggestions I've came across in my journey:

• The section for device management in C is missing entirely in the MSDN docs, and it would be preferable if the sample & tutorials are in the same format as the node/.NET
• Serializer and device management methods are missing in the API Reference
• Device Twin sample is sitting under the serializer folder, very hard to find. I would prefer to have a 'samples' folder in the root of the project, instead of one each for iothub_client/iothub_service_client/serializer
• Maybe have links/description to individual samples in the readme?

[olivierbloch]

Hi @rangedsp
thanks a lot for the suggestions.
A couple comments:

• Yes, we are definitively planning to have a C equivalent of the node and .Net tutorials on the MSDN docs.
• Same thing for the API reference for DM, we need to update the API Reference docs.
• For the location of the serializer samples we'd prefer keeping them under the serializer folder as the serializer is not mandatory for connecting to IoT Hub. That said having direct links to the samples in the main readme could help. I'll go ahead and add these direct links.

Thanks again for chiming in!

[rangedsp]

Thanks @olivierbloch!

I just thought of another thing:
The iothub_client_sample_mqtt_dm sample uses an agent running on raspberry pi, and is not consistent with the other samples (no visual studio solution etc), is there any reason for it being special?

[abhatikar]

It would also be nice to have a nice write up describing the code devicetwin_simplesample .
Currently it only talks about very basic stuff about putting in the connection string only.
Nice thing would be talking about the model, how to manipulate the parameters via JSON using Device explorer and other details a developer would look for. @olivierbloch

[jspaith]

Sorry all for long delay on this one. Since the SDK has drifted so much since this has been created, these turn out to be addressed or moot.

• The section for device management in C is missing entirely in the MSDN docs, and it would be preferable if the sample & tutorials are in the same format as the node/.NET

Our concept of device management has drifted a bit since this. Automatic device configuration (https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-auto-device-config) as well as DPS for provisioning are interesting top-level technologies we've created since this bug was opened.

• Serializer and device management methods are missing in the API Reference

Per https://github.com/Azure/azure-iot-sdk-c/tree/master/serializer, we're continuing to fix serializer bugs but making large continued investments in it.

• Device Twin sample is sitting under the serializer folder, very hard to find. I would prefer to have a 'samples' folder in the root of the project, instead of one each for iothub_client/iothub_service_client/serializer

We've created https://github.com/Azure/azure-iot-sdk-c/tree/master/samples as a one-stop shop to help you find other samples through tree.

We don't want to put ALL the samples under here since we want the technologies - e.g. iothub_client vs iothub_service_client - to be as self-contained in their folders as possible.

• Maybe have links/description to individual samples in the readme?

We've updated many readme's as well as the top level.

• The iothub_client_sample_mqtt_dm sample uses an agent running on raspberry pi

Per https://github.com/Azure/azure-iot-sdk-c/blob/master/iothub_client/samples/iothub_client_sample_mqtt_dm/iothub_client_sample_mqtt_dm.c, this sample is more or less deprecated at this point.

• It would also be nice to have a nice write up describing the code devicetwin_simplesample .

This is part of the serializer that we're not investing in as much. However, we've created a more extensive sample of twin showing how to deal with proper json. https://github.com/Azure/azure-iot-sdk-c/tree/master/iothub_client/samples/iothub_client_device_twin_and_methods_sample

If there's any other docs that aren't clear, please let us know.

[az-iot-builder-01]

@rangedsp, @abhatikar, thank you for your contribution to our open-sourced project! Please help us improve by filling out this 2-minute customer satisfaction survey