Missing a developer guide

[kennu]

Is your feature request related to a problem? Please describe.
In my view, AWS IoT Device SDK v2 for Python is missing a developer guide. Currently there is a steep learning curve in understanding how to use the API. The API was much simpler in v1 and didn't require much of a guide. Now it's extremely complicated, requiring knowledge of many classes, attributes and methods. There is a big chance of misunderstanding how to use the API by only reading the reference.

Describe the solution you'd like
There should be a developer guide, which explains how we are intended to use the IoT Device SDK. This guide would explain common use cases like publishing messages to topics, subscribing to topics, managing thing shadows etc. The samples folder probably contains a lot of useful material around which the developer guide could be written.

Describe alternatives you've considered
There is an API reference, which is difficult to approach and to understand, and there is a link to the generic AWS IoT Developer Guide, which doesn't help much in understanding how to use the IoT Device SDK.

[kennu]

I might also add that I'm specifically trying to understand how to use the awsiot.greengrasscoreipc module. There is no sample code e.g. about subscribing to topics. I can eventually figure it out, but I would prefer to have a developer guide that would explain it to me right away.

[jmklix]

There is more information and examples about what you are looking for here: SubscribeToIoTCoreRequest(). This is grouped under the Greengrass developer guide, so links to that should probably be added to the readme.

I'm assuming you might still want a developer guide. If one was created is there anything not mentioned above that you would want included?

[kennu]

Thanks @jmklix, that example was really hard to find, as the ToC / headings don't mention anything about AWS IoT Device SDK v2 for Python or any other SDK.

I still think a developer guide would be a good idea. In addition to basic use case guidance, an introductory chapter could have helped better understand the somewhat unusual style of API design, which includes "requests", "operations", "futures" and other concepts. At this point, after spending enough hours on it, I'm starting to get it, but I'd like to help others be productive right away without spending the hours.

[kennu]

By the way, it was also hard to find information about how to unsubscribe with IPC. I finally noticed this comment in the example:

# To stop subscribing, close the operation stream.
operation.close()

If you just try to search for "unsubscribe" in the reference documentation, you won't find anything.

[kennu]

Another thing that causes a lot of confusion are the subtle differences between SubscribeToIoTCoreStreamHandler and SubscribeToTopicStreamHandler. The former calls its topics .topic_name and the latter calls them .topic. The former calls its message content .message.payload and the latter calls them .binary_message.message. Frankly I don't understand why all this is so complicated and inconsistent. A lot of precious development time goes into figuring out the quirks of the SDK v2. The v1 version was much simpler and more intuitive.

[jrichrd]

+1 to kennu's comment r.e. documentation for V2. To deploy a simple Python application I had to search across the IoT Core Documentation, Github, Blog posts, IoT Atlas, Workshops and Support articles and found many inconsistencies and contradictions. Several sections of the IoT Core documentation are obsolete with tutorials that leverage the V1 SDK e.g. from AWSIoTPythonSDK.MQTTLib import AWSIoTMQTTShadowClient.

As mentioned the V2 SDK is more complex and seems to require boilerplate code of which I could find no official documentation e.g.

event_loop_group = io.EventLoopGroup(1)
host_resolver = io.DefaultHostResolver(event_loop_group)

I did find an explanation from an SDE on another thread @ aws/aws-iot-device-sdk-cpp-v2#349
I'm unsure of how I can develop a production grade product without documentation of how the SDK functions else I'm including undocumented code in my product. Thanks!

[zachglee]

+1 to this issue. What I want is at least some basic getting started code snippet that shows how to do basic stuff like connect, pub, sub via python code. The pubsub.py example script is fine, but it seems to be using a bunch of code internal to this library that is not easily accessible when I import awsiot.

[lysol]

+1 to this issue. What I want is at least some basic getting started code snippet that shows how to do basic stuff like connect, pub, sub via python code. The pubsub.py example script is fine, but it seems to be using a bunch of code internal to this library that is not easily accessible when I import awsiot.

Agree with this. The pubsub example seems to be outdated or incorrect, the subscribe method is invoked with a completely different set of arguments from the SubscribePacket that seems to be required.

[bretambrose]

+1 to this issue. What I want is at least some basic getting started code snippet that shows how to do basic stuff like connect, pub, sub via python code. The pubsub.py example script is fine, but it seems to be using a bunch of code internal to this library that is not easily accessible when I import awsiot.

Agree with this. The pubsub example seems to be outdated or incorrect, the subscribe method is invoked with a completely different set of arguments from the SubscribePacket that seems to be required.

It sounds like you're using the MQTT5 client. The pubsub sample uses the 311 client; an MQTT5-based pubsub is also available. MQTT5 has a user guide. Generated API docs for MQTT5 are here.