From bef3f442f6323c12af8e58dffc035842158f6e7c Mon Sep 17 00:00:00 2001
From: George Rawlinson <george@rawlinson.net.nz>
Date: Sun, 8 Nov 2020 10:05:30 +1300
Subject: [PATCH] docs: expand examples in readme

---
 README.rst | 51 ++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 48 insertions(+), 3 deletions(-)

diff --git a/README.rst b/README.rst
index d2b98e7..6e0a752 100644
--- a/README.rst
+++ b/README.rst
@@ -13,6 +13,9 @@ The following metrics are accessible:
 Usage
 -----
 
+Setup
+~~~~~
+
 ::
 
     # smbmc_example.py
@@ -21,18 +24,60 @@ Usage
     # initialise client with connection details
     c = Client(IPMI_SERVER, IPMI_USER, IPMI_PASS)
 
-    # retrieve session token
+    # retrieve session token (usually lasts 30 minutes)
+    # optional: the library maintains session tokens internally.
     c.login()
 
+
+Sensor Metrics
+~~~~~~~~~~~~~~
+
+::
+
     # obtain sensor metrics
     sensors = c.get_sensor_metrics()
 
-    # and pmbus metrics
+    for sensor in sensors:
+        print(sensor.__dict__)
+
+    # output (some removed for brevity)
+    {'id': 0, 'name': 'System Temp', 'type': <SensorTypeEnum.TEMPERATURE: 1>, 'unit': <SensorUnitEnum.DEGREES_CELSIUS: 1>, 'state': <SensorStateEnum.PRESENT: 1>, 'flags': None, 'reading': 28.0, 'lnr': -9.0, 'lc': -7.0, 'lnc': -5.0, 'unc': 80.0, 'uc': 85.0, 'unr': 90.0}
+    {'id': 1, 'name': '12VCC', 'type': <SensorTypeEnum.VOLTAGE: 2>, 'unit': <SensorUnitEnum.VOLTS: 4>, 'state': <SensorStateEnum.PRESENT: 1>, 'flags': None, 'reading': 12.192, 'lnr': 10.144, 'lc': 10.272, 'lnc': 10.784, 'unc': 12.96, 'uc': 13.28, 'unr': 13.408}
+    {'id': 9, 'name': 'FAN1', 'type': <SensorTypeEnum.FAN: 4>, 'unit': <SensorUnitEnum.RPM: 18>, 'state': <SensorStateEnum.PRESENT: 1>, 'flags': None, 'reading': 3500.0, 'lnr': 400.0, 'lc': 600.0, 'lnc': 800.0, 'unc': 25300.0, 'uc': 25400.0, 'unr': 25500.0}
+    {'id': 10, 'name': 'FAN2', 'type': <SensorTypeEnum.FAN: 4>, 'unit': <SensorUnitEnum.RPM: 18>, 'state': <SensorStateEnum.NOT_PRESENT: 2>, 'flags': None, 'reading': 0.0, 'lnr': 400.0, 'lc': 600.0, 'lnc': 800.0, 'unc': 25300.0, 'uc': 25400.0, 'unr': 25500.0}
+    {'id': 19, 'name': 'SAS2 FTemp1', 'type': <SensorTypeEnum.TEMPERATURE: 1>, 'unit': <SensorUnitEnum.DEGREES_CELSIUS: 1>, 'state': <SensorStateEnum.PRESENT: 1>, 'flags': None, 'reading': 30.0, 'lnr': -9.0, 'lc': -7.0, 'lnc': -5.0, 'unc': 75.0, 'uc': 77.0, 'unr': 79.0}
+    {'id': 27, 'name': 'PS2 Status', 'type': <SensorTypeEnum.POWER_SUPPLY: 8>, 'unit': <SensorUnitEnum.UNSPECIFIED: 0>, 'state': <SensorStateEnum.PRESENT: 1>, 'flags': <PowerSupplyFlag.PRESENCE_DETECTED: 1>, 'reading': 0, 'lnr': 0, 'lc': 0, 'lnc': 0, 'unc': 0, 'uc': 0, 'unr': 0}
+
+PMBus Metrics
+~~~~~~~~~~~~~
+
+::
+
+    # obtain pmbus metrics
     power_supplies = c.get_pmbus_metrics()
 
-    # or, retrieve all known metrics
+    for psu in power_supplies:
+        print(psu.__dict__)
+
+    # output
+    {'id': 0, 'name': '', 'status': 'ff', 'type': '0', 'input_voltage': 0, 'input_current': 0.0, 'input_power': 0, 'output_voltage': 0.0, 'output_current': 0.0, 'output_power': 0, 'temp_1': 0, 'temp_2': 0, 'fan_1': 0, 'fan_2': 0}
+    {'id': 1, 'name': 'FAKE_PSU_SERIAL', 'status': '1', 'type': '1', 'input_voltage': 236, 'input_current': 0.359, 'input_power': 85, 'output_voltage': 12.1, 'output_current': 5.75, 'output_power': 69, 'temp_1': 38, 'temp_2': 53, 'fan_1': 2894, 'fan_2': 3810}
+
+
+All Metrics
+~~~~~~~~~~~
+
+::
+
+    # obtain all metrics
     metrics = c.get_metrics()
 
+    print(metrics)
+
+    # output
+    {'pmbus': [], 'sensor': []}
+
+
 Contributing
 ------------