Updated documentation for metrics

Author: benmod

README.md

@@ -44,7 +44,7 @@ You can install the library by running `pip install openpaygo` or adding `openpa
 
 You can use the `generate_token()` function to generate an OpenPAYGOToken Token. The function takes the following parameters, and they should match the configuration in the hardware of the device: 
 
-- `secret_key` (required): The secret key of the device. Must be passed as an hexadecimal string (with 32 characters). 
+- `secret_key` (required): The secret key of the device. Must be passed as an hexadecimal string with 32 characters (e.g. `dac86b1a29ab82edc5fbbc41ec9530f6`). 
 - `count` (required): The token count used to make the last token.
 - `value` (optional): The value to be passed in the token (typically the number of days of activation). Optional if the `token_type` is Disable PAYG or Counter Sync. The value must be between 0 and 995. 
 - `token_type` (optional): Used to set the type of token (default is Add Time). Token types can be found in the `TokenType` class: ADD_TIME, SET_TIME, DISABLE_PAYG, COUNTER_SYNC. 
@@ -100,7 +100,7 @@ device.save() # We save the new count that we set for the device
 You can use the `decode_token()` function to generate an OpenPAYGOToken Token. The function takes the following parameters, and they should match the configuration in the hardware of the device: 
 
 - `token` (required): The token that was given by the user, as a string
-- `secret_key` (required): The secret key of the device
+- `secret_key` (required): The secret key of the device as a string with 32 hexadecimal characters (e.g. `dac86b1a29ab82edc5fbbc41ec9530f6`)
 - `count` (required): The token count of the last valid token. When a device is new, this is 1. 
 - `used_counts` (optional): An array of recently used token counts, as returned by the function itself after the last valid token was decoded. This allows for handling unordered token entry. 
 - `starting_code` (optional): If not provided, it is generated according to the method defined in the standard (SipHash-2-4 of the key, transformed to digit by the same method as the token generation).
@@ -164,19 +164,73 @@ elif token_type == TokenType.INVALID:
 You can use the `MetricsRequestHandler` object to create a new OpenPAYGO Metrics request from start to finish. It accepts the following initial inputs: 
 - `serial_number` (required): The serial number of the device
 - `data_format` (optional): The data format, provided as dictionnary matching the data format object specifications. 
-- `secret_key` (optional): The secret key provided as a string containing 32 hexadecimal characters. Required if `auth_method` is defined. 
+- `secret_key` (optional): The secret key provided as a string containing 32 hexadecimal characters (e.g. `dac86b1a29ab82edc5fbbc41ec9530f6`). Required if `auth_method` is defined. 
 - `auth_method` (optional): One of the auth method contained in the `AuthMethod` class. 
 
 It provides the following methods:
 - `set_timestamp(timestamp)`: Used to set the `timestamp` of the request. 
 - `set_request_count(request_count)`: Used to set the `request_count` of the request. 
+- `set_data(data)`: Used to set the `data` of the request, should be set in simple format as a dictionnay. 
+- `set_historical_data(data)`: Used to set the `historical_data` of the request, should be set in simple format as a dictionnary. The data is assumed to be separated by the `historical_data_interval` unless an explicit timestamp is provided. 
+- `get_simple_request_payload()`: Returns the payload in simple format as a string containing JSON and including the authentication signature. 
+- `get_condensed_request_payload()`: Returns the payload in condensed format as a string containing JSON and including the authentication signature. It requires `data_format` to be set. The data is automatically condensed from the set data and the data format and the signature is automatically generated. 
+
+
+**Example - Full Request flow from device side:**
+
+```python
+from openpaygo import MetricsRequestHandler, AuthMethod
+import requests
+
+# We assume the users enters a token and that the device state is saved in my_device_state
+...
+
+metrics_request = MetricsRequestHandler(
+      serial_number=my_device_state.serial_number,
+      secret_key=my_device_state.secret_key,
+      data_format=my_device_state.data_format,
+      auth_method=AuthMethod.RECURSIVE_DATA_AUTH
+)
+
+metrics_requestset_timestamp(1611583070)
+metrics_requestset_data({
+  "token_count": 3,
+  "tampered": False,
+  "firmware_version": "1.2.3"
+})
+# Here we assume that the data we send is separated by 60 seconds as per the data format
+metrics_requestset_historical_data([
+  {
+      "panel_voltage": 12.31,
+      "battery_voltage": 12.32,
+      "panel_current": 1.23,
+      "battery_current": -1.23,
+  },
+  {
+      "panel_voltage": 12.30,
+      "battery_voltage": 12.31,
+      "panel_current": 1.22,
+      "battery_current": -1.21,
+  }
+])
+payload = metrics_requestget_condensed_request_payload()
+
+# We can now proceed to send the payload to the URL
+# It looks something like `{"sn":"aaa111222","df":1234,"ts":1611583070,"d":[3,false,"1.2.3"],"hd":[[12.31,12.32,1.23,-1.23],[12.3,12.31,1.22,-1.21]],"a":"raa5cb1fda302cf94e"}`
+response = requests.post('https://<base_url>/dd', data=payload, headers={'Content-Type':'application/json'})
+try:
+  response.json().get('tkl', [])
+  for tokens in tkl:
+    # Here we decode the tokens received from the server and apply them (see example above)
+    ...
+```
 
 
 ### Handling a Request and Generating a Response (Server Side)
 
 You can use the `MetricsResponseHandler` object to process your OpenPAYGO Metrics request from start to finish. It accepts the following initial inputs: 
 - `metrics_payload` (required): The OpenPAYGO Metrics payload, as a string containing the JSON payload. 
-- `secret_key` (optional): The secret key provided as a string containing 32 hexadecimal characters
+- `secret_key` (optional): The secret key provided as a string containing 32 hexadecimal characters (e.g. `dac86b1a29ab82edc5fbbc41ec9530f6`)
 - `data_format` (optional): The data format, provided as dictionnary matching the data format object specifications. 
 
 It provides the following methods:
@@ -191,7 +245,7 @@ It provides the following methods:
 - `get_answer()`: Will return the answer as a string based on the request and the data added to answer, it will automatically handle the authentication and fomatting. 
 
 
-**Example - Full Request flow:**
+**Example - Full Request flow from server side:**
 
 ```python
 from openpaygo import MetricsHandler