Not intuitive how to create a device using CLI. about azure-iot-cli-extension

[jongio]

@olivierbloch / @chrissie926 / @pierreca / @wickste / @digimaun / @c-ryan-k - Thoughts on this experience? The scenario is that I want to create a device and had trouble discovering how to from the CLI itself (w/o docs). First inclination was to use az iot device. I think we should optimize for that.

Here's what I recommend:

1. Move commands under az iot hub device-identity to az iot device
2. Remove az iot hub device-identity

[digimaun]

A long time ago (very early iterations), the az iot hub device-identity ... CRUD set of commands used to be under az iot device. Moving closer towards the widely announced release early this year we reformulated the entire command space to this current set.

On one hand, az iot hub device-identity ... makes sense from an Azure IoT architecture perspective (i.e. interacting with device representation (device-identity) on your IoT assets manager (iot hub).

On the other hand az iot device ... is intuitive and fast...you don't have to think about it much. In the reformulated command set this space is primarily for device perspective operation (C2D/D2C messaging, basic device simulation, file upload).

One alternative idea discussed is command aliases (so you can do say az iot hub device-identity create or az iot device create) but I am not a fan of this because the user is overwhelmed with superfluous options ("whats the difference between these device create commands? which should I use?").

Also I would note (an obvious point) that base command name changes are 'heavy operations' in the sense that you have to at least:

• Deprecate existing stuff (and come up with removal plan)
• Update downstream/dependent tools and components to use the new stuff
• Related to last point: Update documentation everywhere...more of a thing for non-automation generated docs.

Thoughts @olivierbloch and @chrissie926 ??

[jongio]

@c-ryan-k @iluican - Thoughts on this thread?

[c-ryan-k]

I do agree that az iot hub device-identity create can be a bit confusing (as well as tedious to type compared to the alternative).

Like @digimaun mentioned, from an architecture perspective it makes sense, however once a 'device-identity' has been created, we then use az iot device to interact with that 'device' (c2d, d2c, etc) - so syntactically at that point we do treat it like a device rather than an identity.

There's also a good point about aliases. I'd have no issue being able to use both, and that might even be the first step towards migrating to only using az iot device in the future.

While it is a bit overwhelming having multiple commands that do the same thing, there might be a chance that they don't in the future.

So to sum up what we currently provide:

1. az iot hub device-identity
   a. CRUD
   b. Import / Export
   c. List All
2. az iot device
   a. D2C / C2D
   b. Simulation
   c. File upload

I'd say there's definitely a case to be made for moving / aliasing CRUD operations into az iot device, but what about list, import, and export?

[jongio]

Thanks Ryan. I would like to see all device commands under az iot device.

[wickste]

I agree with Jon here. This seems like the right direction.

Anyone know if there is Azure CLI guidance or precedence for deprecating and removing commands? If not, I will follow up on that.

[digimaun]

There is precedence. We've deprecated and removed lots of commands in the past. Both in the IoT command module and IoT extension.

[digimaun]

Closing the issue as there has not been any discussion or activity for a loong time. Happy to talk more though.