Update required message types and add v2.0 ex. (home-assistant#1728)

brahmafear · MartinHjelmare · commit dd334853205a · 2017-01-08T17:50:03.000+01:00
* Update required message types and add v2.0 ex.

Changed wording of section listing required message types to make more clear the necessity of sending V_STATUS messages along with V_PERCENTAGE or V_RGB messages.  Also, added a MySensors v2.x example sketch which is substantially different from v.1.x.  Example sketch taken from MySensors github repo with some comments removed.

* Updated example sketch

Simplified and style corrected.

* V_LIGHT changed to V_STATUS ...

Updated to use non-deprecated types.  Also updated library link.

* Updated wording of type description

Updated description of which type messages to send in response to events.  This is a hard requirement to fully explain, but hopefully the example sketches will provide guidance.
diff --git a/source/_components/light.mysensors.markdown b/source/_components/light.mysensors.markdown
@@ -30,11 +30,11 @@ S_TYPE      | V_TYPE
 S_DIMMER    | [V_DIMMER\* or V_PERCENTAGE\*], [V_LIGHT\* or V_STATUS\*]
 S_RGB_LIGHT | V_RGB*, [V_LIGHT\* or V_STATUS\*], [V_DIMMER or V_PERCENTAGE]
 
-V_TYPES with a star (\*) denotes required V_TYPES. Use either V_LIGHT or V_STATUS and either V_DIMMER or V_PERCENTAGE for an applicable actuator.
+V_TYPES with a star (\*) denote V_TYPES that should be sent at sketch startup. For an S_DIMMER, send both a V_DIMMER/V_PERCENTAGE and a V_LIGHT/V_STATUS message.  For an S_RGB_LIGHT, send both a V_RGB and a V_LIGHT/V_STATUS message with a V_DIMMER/V_PERCENTAGE message being optional.  Sketch should acknowledge a command sent from controller with the same type.  If command invokes a change to off state (including a V_PERCENTAGE or V_RGB message of zero), only a V_STATUS of zero message should be sent.  See sketches below for examples.  
 
 For more information, visit the [serial api] of MySensors.
 
-### {% linkable_title Example sketch %}
+### {% linkable_title MySensors 1.x example sketch %}
 
 ```cpp
 /*
@@ -108,6 +108,138 @@ void incomingMessage(const MyMessage &message) {
     }
 }
 ```
+### {% linkable_title MySensors 2.x example sketch %}
 
+```cpp
+/* 
+ * Example Dimmable Light
+ * Code adapted from http://github.com/mysensors/MySensors/tree/master/examples/DimmableLight
+ * 
+ * Documentation: http://www.mysensors.org
+ * Support Forum: http://forum.mysensors.org
+ *
+ */
+
+// Enable debug prints
+#define MY_DEBUG
+
+// Enable and select radio type attached
+#define MY_RADIO_NRF24
+//#define MY_RADIO_RFM69
+
+#include <MySensors.h>
+
+#define CHILD_ID_LIGHT 1
+
+#define LIGHT_OFF 0
+#define LIGHT_ON 1
+
+#define SN "Dimmable Light"
+#define SV "1.0"
+
+int16_t last_state = LIGHT_ON;
+int16_t last_dim = 100;
+
+MyMessage light_msg( CHILD_ID_LIGHT, V_STATUS );
+MyMessage dimmer_msg( CHILD_ID_LIGHT, V_PERCENTAGE );
+
+void setup()
+{
+  update_light();
+  Serial.println( "Node ready to receive messages..." );
+}
+
+void loop()
+{
+  //In MySensors2.x, first message must come from within loop()
+  static bool first_message_sent = false;
+  if ( first_message_sent == false ) {
+    Serial.println( "Sending initial state..." );
+    send_dimmer_message();
+    send_status_message();
+    first_message_sent = true;
+  }
+}
+
+void presentation()
+{
+  // Send the sketch version information to the gateway
+  sendSketchInfo( SN, SV );
+  present( CHILD_ID_LIGHT, S_DIMMER );
+}
+
+void receive(const MyMessage &message)
+{
+  //When receiving a V_STATUS command, switch the light between OFF 
+  //and the last received dimmer value  
+  if ( message.type == V_STATUS ) {
+    Serial.println( "V_STATUS command received..." );
+
+    int lstate = message.getInt();
+    if (( lstate < 0 ) || ( lstate > 1 )) {
+      Serial.println( "V_STATUS data invalid (should be 0/1)" );
+      return;
+    }
+    last_state = lstate;
+
+    //If last dimmer state is zero, set dimmer to 100
+    if (( last_state == LIGHT_ON ) && ( last_dim == 0 )) {
+      last_dim=100;
+    }
+
+    //Update constroller status
+    send_status_message();
+    
+  } else if ( message.type == V_PERCENTAGE ) {
+    Serial.println( "V_PERCENTAGE command received..." );
+    int dim_value = constrain( message.getInt(), 0, 100 );
+    if ( dim_value == 0 ) {
+      last_state = LIGHT_OFF;
+
+      //Update constroller with dimmer value & status
+      send_dimmer_message();
+      send_status_message();      
+    } else {
+      last_state = LIGHT_ON;
+      last_dim = dim_value;
+     
+      //Update constroller with dimmer value
+      send_dimmer_message();
+    }
+        
+  } else {
+    Serial.println( "Invalid command received..." );
+    return;
+  }
+
+  //Here you set the actual light state/level
+  update_light();
+}
+
+void update_light()
+{
+  //For this example, just print the light status to console.
+  if ( last_state == LIGHT_OFF ) {
+    Serial.println( "Light state: OFF" );
+  } else {
+    Serial.print( "Light state: ON, Level: " );
+    Serial.println( last_dim );
+  }
+}
+
+void send_dimmer_message()
+{
+  send( dimmer_msg.set( last_dim ) );
+}
+
+void send_status_message()
+{
+  if ( last_state == LIGHT_OFF ) {
+    send( light_msg.set( (int16_t)0) );
+  } else {
+    send( light_msg.set( (int16_t)1) );
+  }
+}
+```
 [main component]: /components/mysensors/
-[serial api]: https://www.mysensors.org/download/serial_api_15
+[serial api]: http://www.mysensors.org/download
