[siemensrds] Update to documentation (#13913)

* [siemensrds] resolve issue #13906
* [siemensrds] add chapter to readme

Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>

diff --git a/bundles/org.openhab.binding.siemensrds/README.md b/bundles/org.openhab.binding.siemensrds/README.md
index 41b4951a20af05d3a6c7b1533889f2b7cfa070cb..67993549e38110c2e0291b8df154ed51bc384e63 100644 (file)
--- a/bundles/org.openhab.binding.siemensrds/README.md
+++ b/bundles/org.openhab.binding.siemensrds/README.md
@@ -41,6 +41,7 @@ However the Climatix IC cloud server is also used for supporting private custome
 But Siemens customer support people are often unaware of the latter fact, so when you ask them for the API key for the RDS smart thermostat range, their first reaction might often be to say you are talking nonsense!
 Do not accept that answer!
 You need to insist that you are requesting the Climatix IC cloud server API key _**for the RDS smart thermostat range**_ – it is a <u>different</u> key than those for OEM commercial customers.
+You can also get the API key by observing the traffic between your RDS App and the server, as explained [below](#observing-the-api-key).
 
 Note: You must create ONLY ONE Thing of the type Climatix IC Account; duplicate Climatix IC Account Things risk causing communication errors with the cloud server.   
 
@@ -71,18 +72,26 @@ The RDS Smart Thermostat supports several channels as shown below.
 | hotWaterAutoMode         | Switch             | The Domestic Water Heating is in Automatic Mode (Off=Manual, On=Automatic)  |
 | hotWaterOutputState      | Switch             | The On/Off state of the domestic water heating                              |
 
+## Observing the API Key
+
+You can find your API key by observing the traffic between the RDS App on a phone/tablet and the remote ClimatixIC server.
+The traffic is encrypted using SSL so regular network analyzers like [WireShark](https://www.wireshark.org/) will not work.
+But you can use an interposing SSL proxy server like [Charles Proxy](https://www.charlesproxy.com/).
+The general technique of using Charles Proxy to observe SSL App/server traffic is explained in this [video](https://m.youtube.com/watch?v=r7aV39-CKg4).
+And specifically for this case you can examine the SSL traffic to 'api.climatixic.com', and search for the 'Ocp-Apim-Subscription-Key’ header.
+
 ## Full Example
 
 ### `demo.things` File
 
-```
+```java
 Bridge siemensrds:climatixic:mybridgename "Climatix IC Account" [ userEmail="email@example.com", userPassword="secret", apiKey="32-character-code-provided-by-siemens", pollingInterval=60 ]
 }
 ```
 
 To manually configure an RDS Smart Thermostat Thing requires knowledge of the "Plant Id" which is a unique code used to identify a specific thermostat device in the Siemens Climatix IC cloud server account.
 
-```
+```java
 Bridge siemensrds:climatixic:mybridgename "Climatix IC Account" [ userEmail="email@example.com", userPassword="secret", apiKey="32-character-code-provided-by-siemens", pollingInterval=60 ] {
     Thing rds mydownstairs "Downstairs Thermostat" @ "Hall" [ plantId="Pd0123456-789a-bcde-0123456789abcdef0" ]
     Thing rds myupstairs "Upstairs Thermostat" @ "Landing" [ plantId="Pd0123456-789a-bcde-f0123456789abcdef" ]
@@ -91,7 +100,7 @@ Bridge siemensrds:climatixic:mybridgename "Climatix IC Account" [ userEmail="ema
 
 ### `demo.items` File
 
-```
+```java
 Number:Temperature Upstairs_RoomTemperature "Room Temperature" { channel="siemensrds:rds:mybridgename:myupstairs:roomTemperature" }
 Number:Temperature Upstairs_TargetTemperature "Target Temperature" { channel="siemensrds:rds:mybridgename:myupstairs:targetTemperature" }
 String Upstairs_ThermostatOutputState "Thermostat Output State" { channel="siemensrds:rds:mybridgename:myupstairs:thermostatOutputState" }
@@ -107,7 +116,7 @@ Switch Upstairs_HotWaterOutputState "Hotwater Output State" { channel="siemensrd
 
 ### `demo.sitemap` File
 
-```
+```php
 sitemap siemensrds label="Siemens RDS"
 {
 Frame label="Heating" {

diff --git a/bundles/org.openhab.binding.siemensrds/src/main/java/org/openhab/binding/siemensrds/internal/RdsAccessToken.java b/bundles/org.openhab.binding.siemensrds/src/main/java/org/openhab/binding/siemensrds/internal/RdsAccessToken.java
index 3cc7a51862a124c0658cf21060ce140b87f56728..b2bd19893a7791a1a2d56f62bbe601a2b45f58e4 100644 (file)
--- a/bundles/org.openhab.binding.siemensrds/src/main/java/org/openhab/binding/siemensrds/internal/RdsAccessToken.java
+++ b/bundles/org.openhab.binding.siemensrds/src/main/java/org/openhab/binding/siemensrds/internal/RdsAccessToken.java
@@ -27,6 +27,7 @@ import java.text.ParseException;
 import java.text.SimpleDateFormat;
 import java.util.Calendar;
 import java.util.Date;
+import java.util.Locale;
 
 import javax.net.ssl.HttpsURLConnection;
 
@@ -61,7 +62,7 @@ public class RdsAccessToken {
 
     private @Nullable Date expDate = null;
 
-    /*
+    /**
      * public static method: execute the HTTP POST on the server
      */
     public static String httpGetTokenJson(String apiKey, String payload) throws RdsCloudException, IOException {
@@ -105,14 +106,14 @@ public class RdsAccessToken {
         }
     }
 
-    /*
+    /**
      * public method: parse the JSON, and create a class that encapsulates the data
      */
     public static @Nullable RdsAccessToken createFromJson(String json) {
         return GSON.fromJson(json, RdsAccessToken.class);
     }
 
-    /*
+    /**
      * public method: return the access token
      */
     public String getToken() throws RdsCloudException {
@@ -123,14 +124,14 @@ public class RdsAccessToken {
         throw new RdsCloudException("no access token");
     }
 
-    /*
+    /**
      * public method: check if the token has expired
      */
     public boolean isExpired() {
         Date expDate = this.expDate;
         if (expDate == null) {
             try {
-                expDate = new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss z").parse(expires);
+                expDate = new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss z", Locale.ENGLISH).parse(expires);
             } catch (ParseException e) {
                 logger.debug("isExpired: expiry date parsing exception");