VOL-3266: Added documentation for starting to manage a device
Change-Id: I2abf8c6e39f9edf523ff81ef0e06b57905245d18
diff --git a/docs/ManagingDevice.md b/docs/ManagingDevice.md
new file mode 100644
index 0000000..d5ad632
--- /dev/null
+++ b/docs/ManagingDevice.md
@@ -0,0 +1,54 @@
+# Managing a device
+
+The first API that a NEM would need to excute to start managing a hardware is the StartManagingDevice.
+
+## StartManagingDevice
+
+``` protobuf
+service NativeHWManagementService {
+ // Initializes context for a device and sets up required states
+ // In the call to StartManagingDevice, the fields of ModifiableComponent which are relevant
+ // and their meanings in this context is mentioned below:
+ // name = The unique name that needs to be assigned to this hardware;
+ // class = COMPONENT_TYPE_UNDEFINED;
+ // parent = nil;
+ // alias = Optional;
+ // asset_id = Optional;
+ // uri = IP Address of the Hardware;
+ rpc StartManagingDevice(ModifiableComponent) returns(stream StartManagingDeviceResponse);
+}
+```
+The `uri` is what would carry the IP address of the device and the `name` should be something that would uniquely identify the device.
+
+On reception of this rpc, an implementation of Device Manager should validate the IP address and see if it can talk to/setup connection to the device or not. It should setup any required states that might be needed for it's internal implementation.
+
+The NEM would wait for the `StartManagingDeviceResponse` before it will do any futher actions on this device. This response needs to contain the `uuid` assigned to this device. **For futher RPCs it would be the `uuid` that would be used to identify the device.**
+
+*The device manager implementation should ensure that the `uuid` returned is universally unique and* ***does not change across reboots of the device.*** An example could be that the device manager first connects to the device and learns the serial number of the device and then uses this serial number to generate the `uuid` for the device.
+
+## GetPhysicalInventory
+``` protobuf
+// Get the HW inventory details of the Device
+rpc GetPhysicalInventory(PhysicalInventoryRequest) returns(stream PhysicalInventoryResponse);
+```
+
+This RPC is used to retrieve the entire inventory of components of the Hardware. Again the caller has to wait on the response in a stream as implementations of Device Manager could take time to gather all this information.
+
+## GetHWComponentInfo
+``` protobuf
+// Get the details of a particular HW component
+rpc GetHWComponentInfo(HWComponentInfoGetRequest) returns(stream Component);
+```
+In the call to this RPC, both the `name` and the `uuid` of the component need to be passed in the `HWComponentInfoGetRequest`.
+
+The `name` has to be unique for each of the components of the hardware and the `uuid` has to be universally unique. Implementation of Device Manager need to ensure this. Both of these two attributes are generated by the Device Manager.
+## SetHWComponentInfo
+``` protobuf
+// Sets the permissible attributes of a HW component
+rpc SetHWComponentInfo(HWComponentInfoSetRequest) returns(HWComponentInfoSetResponse);
+```
+In the call to this RPC, both the `name` and the `uuid` of the component need to be passed in the `HWComponentInfoSetRequest`.
+
+Using this RPC, it is possible to modify the `name` of a component, and the Device Manager has to ensure that the name is unique, else it should return an error for this RPC. Although the `name` can be modified, it is recommended that NEM implementations do not do this because Device Managers and take advantage of this and come up with efficient implementations.
+
+
diff --git a/docs/events_metrics.drawio b/docs/events_metrics.drawio
new file mode 100755
index 0000000..1a18b6c
--- /dev/null
+++ b/docs/events_metrics.drawio
@@ -0,0 +1 @@
+<mxfile host="app.diagrams.net" modified="2020-06-17T14:32:30.978Z" agent="5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.61 Safari/537.36" etag="EigMuYxAlA4_x8PwkvI_" version="13.2.6" type="device"><diagram id="yPeOgAjgfKf-2OFRMvG_" name="Page-1">7VtZc6M4EP41rtp5CMVt+zFxjknt5KjJTM3O0xYBYasCiBHytb9+W0YCC/ARj7ETT1ypCmpEC/r7ulu0RMcaxLMb6qWjOxKgqGPqwaxjXXZM07BNs8P/9GCeS7qmnQuGFAeiUyl4wv8hIdSFdIwDlCkdGSERw6kq9EmSIJ8pMo9SMlW7hSRSR029IaoJnnwvqkt/4ICNcmnP0Uv5Z4SHIzmyoYszsSc7C0E28gIyXRJZVx1rQAlh+VE8G6CIG0/aJb/uesXZ4sYoStg2F3y36JdfGLF/ncfn7/GL7z59npwJLRMvGosH7phuBPouQgJq4a7ZXJjC/TUm8sRZtgDqHDoYdjorT8LRkP9/SBH1GKHQ4f7qboFPnJIEbjWDxl83Xx8H8H8QYZB8kkPCveej5jqE2YobMCkZJwHij2PA6ekIM/SUej4/OwX2gWzE4kicFg+GKEOzlRYzChyAwIjEiNE5dJEXWG5+ieBuTyA5LYngSLhHSySwhcwT3BsWmkt44EAg9Aq0zJbQukQTDGY09TsvAUJz1G7jNEIxGMpjmCRymGcqL5EQPiEKNv5U7/BmQZXoCFBtu46qdVBUrd9Gtd8EagGJinIOMUf2NmGIhtzUJVTPrcIX4igakAjCAr/Wur6+sFwX5BxQDDH3PMLDBM7FOAj4AK3gbW6Jt9kW3nYD3hWrQq5I+WEYodk5z2JgC5QE4vDSj7wswz4IM+ZRVhcv2Vw+punmOkSK7WlutzAwCmpJcKN5lSBYt56UURRBBJmo6ptMKkZ4JHjBeYGeZRgKelYVlYyMqY/EVcvZr6LItTcoAkMOEaspAtt686VuKe+Qrb5hu9c8TkmYXGNJn8KmuzPKqTHqby988UB0Mc5q5OJof/GeYaKmEMUTzucjHhfWeSVFEHq854U+HdrCJqDcueg4l+v8VkzTxMXl5GiZcKudZqWT65pu6ZZi+DOjvxcGFnoKvT1VBQnDDLEKyHuB1W0p3b9wcpwxkkKsqOVtNEsJ5QR4o/nb7qsOZjTMygyzISK5bcXzbg2mx9E8454D0ocv39aYTN8hZ/Ifj/zydWJPdoUkqNjV6R7brr3NeXLHnAgmofN/uP01RzZ/Lp+7nAlw8tZctLbNlnCPi7S0mTR51tk05T9W9rXtFZx4bfa1+xVFW2bffUVSWU1Y4tJXFIQ4G3X4nVzXw+D91bfBw/312c/z+5tVfR7YaPGulFLCiE+iGj3BG5nKvIxR8oKkPyfwRlxxcSGSyThCIVuXipuChxpe9hAaiumxRM9oCA1NNGxtCm00vQnvPTboXUuJDppuOhsixKL1iCiG5+STqFeGjY3h4KiTcaOrTrHsXSfj1VxT5PBDhYOmV+5t6LPMkxlmOU26jmj+lCSA45IfvNFCArGOyYQiAkgm9HdkguU6iiLLOjATtngZ38iEMmLYtrscMXSt3zePHDHco/LEtlV4jR154vZUwtWqcW3zpP6K/Ts86dm9Ck96vV14UgYhR4lCZ5C8jO7aUMQbu9NuY3hy30NCc5wKPXdNaKBIc8wKQ/uaY/TLX6Vs0DZh68UDUbE/f7zlazBIG2qrq/YBnlRFouYQer5achiAjfBiHnyPpsvFhi3KE7pantD94kW3FFr8F4ZbFLif+ORuUd/GyVCuaQxeVd0uxA0GeJc2uQGOiWrEbTIBNybcIf5wo1ySaRIRL7iN+ervn26N72ngMXQHAQf72YAkIR6OqVj2+8NNo2naHgxwmlUBozols45eFahXYn9QsASfh5AFP1aluxqyWAqCWEOTfNtCAS5uAHxJg+4lwaJkVFFVGwx0x7nXbSAZPnUuWV2VS1ZT8bl3UC41VZ93DVu/F4SkIEu9ZJcYmGvJ47sa0XONlWFrzvGKyPcug/wV9++PML/KNc2KazbugjqkZ/ZP1DPX+F+To+6yW+dEOOlUFiTMhnRxUE5Kxcr6ksdnASEl8dqpx8f0YAu8nQre7rGnB/IZTnDj7L43Fry9XbRmS9gdb1/NvjF7e5tszC2W7A62a7LB3B9bKN/3Fkr5Wcop76E0V6wZn/QmSrNp5e5je/2ChHtP9W9ur73Z1h7ad/PJTOsYt/j9DDTL7+PygFB+ZWhd/Q8=</diagram></mxfile>
\ No newline at end of file
diff --git a/docs/managing_device.drawio b/docs/managing_device.drawio
new file mode 100755
index 0000000..60b311d
--- /dev/null
+++ b/docs/managing_device.drawio
@@ -0,0 +1 @@
+<mxfile host="app.diagrams.net" modified="2020-06-26T12:05:52.057Z" agent="5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.106 Safari/537.36" etag="YWQTOr6kjvNCYbqAhE6m" version="13.3.0" type="device"><diagram id="u7MiE9SF2knlp-uFeZNf" name="Page-1">3Vhtk6I4EP41flyLJIjyUeflbqt2dqz16vZzJFFSFwkHYXX2118HghCj48yc7s4uZQl0N53Q/TzdIQNys9n9UdA8fVCMywEO2G5AbgcYoxDjgfkF7KmRjEncCNaFYNaoEyzEd26FgZVWgvHSMdRKSS1yV5ioLOOJdmS0KNTWNVsp6Y6a0zX3BIuESl/6VTCdNtLJKOjkf3KxTtuRUWA1G9oaW0GZUqa2PRG5G5CbQindXG12N1ya4LVxaZ67P6HdT6zgmX7JA/hxvP2iZrv54jPOpvnfJd3hD6Tx8o3Kyr7wY84LqlUB0s93D3bq+qmNx/4t0IDMVkLKGyXB2OgIj1jAwG5W6kL9w3uaOI7QZASaVG+kfXhdUCZg7j0zNgJ4MONYZdpiARG4t7Pkhea7k6+P9kEFNHK14bp4AhP7QNTmwQJxYm+3XVZRMGpkaS+jbaapBdJ677mLNVzYcL8i9KEXei/YnAEW7W2mMhNanrGpgXUnYbRMObNB7cW38WZcvDFio3g8JGQURHFYH5ETP5NPP4CBH8C98FgE7eBzJWBOXa7GeDjCAcH2zx2YHPgrVVUk3LroE8DzShxHIT5wpGmx5tpzVGd3H563J3zkJXwBI5oJPtCMrkW2NnPJ4O/x018eFgD52k2wyzKLhj4lrYhKsc7gNoG8c5DPDI8ElLipVWwEY2aY2TYVmi9ympgxt1DQQVaoKmM1vgIzpkP/Hkuj9t7OGF2AsihyKRv6lA3DI4g7zOvFKIuQl8KPm1zyDbwQ1UKZ3KnVAEfSpGpZOBmM/q1Mqa+j9KGswzYFA0TyXc3WVg9Xa3O+5d8EJMKiAxL325RiQs6XYnQkr1crxQi/k1oMI9bF7CwGT8cWo2E8GU/CMa6P0K2dcTiM+8f4ajWcTPAQjfC4PSaXKeJk8nOLOPJXTC3fDVNezHiP7nUvaBtBy/3GMUy08d1YvgSabYn/RJdczlUp6upEbrXKjzSApdJabQ67C8ynhXciaVmKpBXfC9ma+RwAidUHx+pPUB+XWJ+gMBqOXFQF+Ip4dosWit+8DDnj6NoI9heex9Ybv2x3Cd/ZOh/5675nGczlUm3vOsGsFoAiVYX4DvGi8qf1nvB5QqLxASH3nf4KhPRHC9/aVCZuc/rhPWX843rKF17mKivfUW+xXvuNJXAB3nWfrrf4H0D93uJw4f83GjI5QBpA5JoLp+Mcen2jOePoyrBu69zlYc11lQ/2e37Nd9dWQCLsp/PLoA0dLjeXTFVLyS3Yjn4Dn/zoBsyZ4/7+Mq0rdlsXDvzqubdxUHaY2Ys1Lxz5i4VMminTldlMgLMJapUkvCxXlfHXVZggqXczlE5ry+n8YwmnZaOREgh6KiVGrSp9Ph05LwS8qdnWaB+ad6JnsnW48Oi2OWq3tqrhdhXbWOKgpzOqIbnU7uTB6pLgI42TvLbAnEg93Hbbzg3bu817cvcf</diagram></mxfile>
\ No newline at end of file
diff --git a/docs/managing_device.png b/docs/managing_device.png
new file mode 100755
index 0000000..5542ce3
--- /dev/null
+++ b/docs/managing_device.png
Binary files differ
