Converting a sketch from 1.5.x to 2.0.x

  • Admin

    2.0.x allow configuration (old MyConfig stuff) to be done directly in the sketch using simple c #defines. You can still make modification in MyConfig if you want to override the default values once and for all.

    It is important to do these defines before including MySensors.h, otherwise they will go unnoticed when the library evaluates which parts to include.

    The most common thing you need to do is to decide which radio to use (or not to use). We currently support three different transport layers. Only activate ONE transport per node.

    // Activate one of these
    #define MY_RADIO_NRF24
    #define MY_RADIO_RFM69
    #define MY_RS485

    In addition to the transport you can also allow the node to be a gateway (communicating to the controller). We currently offer a few variants here as well. Note that ESP8266 is always considered to be a gateway node (but it can still communicate with a sub-network of none-esp sensor nodes). If you want to enable gateway functionality enable one of these:

    // Enable serial gateway
    // Enable gateway ethernet for a ENC28J60 module 
    #define MY_GATEWAY_ENC28J60
    // Enable gateway for a W5100 ethernet module 
    #define MY_GATEWAY_W5100
    // Enable gateway for a ENC28J60 ethernet for a  module 
    #define MY_GATEWAY_ENC28J60
    // Enable a MQTT client gateway for W5100 or ESP node

    Each type of gateway has additional configuration available (ip settings etc). Please look at the prepared example for more details.

    To upgrade a sketch old 1.5 sketch to 2.0 there is just a few steps to go through.

    • Remove the MySensors gw; class initialization and gw.begin()-call. It's no longer needed. Use #defines to set radio channels or other settings. They are all documented in MyConfig.h.

    • The library now calls process() automatically. So you must remove it from you main loop().

    • Remove the gw. part before any library call. It's no longer needed as library functions is available in the main scoop. For instance gw.send(msg) should just be send(msg).

    • The controller can now re-request presentation information from a node. This means we have to move all node presentation to a new special function presentation() {} . This will be called at node startup or when controller requests a new presentation.

    So if your old node had this:

    void setup()  
      gw.sendSketchInfo("Distance Sensor", "1.0");
      gw.present(CHILD_ID, S_DISTANCE);

    Do like this instead:

    void presentation()  
      sendSketchInfo("Distance Sensor", "1.0");
      present(CHILD_ID, S_DISTANCE);

    If you need to do initialization before the MySensors library starts up, define a

    void before() {
        // This will execute before MySensors starts up

    You can still use setup() which is executed AFTER mysensors has been initialised.

    void setup() {

    To handle received messages, define the following function in your sketch

    void receive(const MyMessage &message) {
        // Handle incoming message

    If your node requests time using requestTime(). The following function is used to pick up the response.

    void receiveTime(unsigned long ts) {

    Here follows a small sample of the defines you can use in your sketch

    #define MY_DEBUG    // Enables debug messages in the serial log
    #define MY_REPEATER_FEATURE  // Enables repeater functionality for a radio node
    #define MY_BAUD_RATE  9600 // Sets the serial baud rate for console and serial gateway
    #define MY_NODE_ID 42 // Sets a static id for a node
    #define MY_PARENT_NODE_ID xx // Sets a static parent node id
    #define MY_OTA_FIRMWARE_FEATURE  // Enables OTA firmware updates
    #define MY_RF24_CE_PIN 9    // Radio specific settings for RF24
    #define MY_RF24_CS_PIN 10 // Radio specific settings for RF24 (you'll find similar config for RFM69)
    #define MY_INCLUSION_MODE_FEATURE // Enables inclusion mode (for a gateway)
    #define MY_INCLUSION_BUTTON_FEATURE // Eables inclusion mode button (for a gateway)
    #define MY_LEDS_BLINKING_FEATURE // Enables transmission led feature for a node or gateway
    #define MY_SIGNING_ATSHA204 // Enables hardware signing using ATSHA204
    #define MY_SIGNING_SOFT // Enables software signing

    Security related settings (HMAC and AES keys among other things) are now configured using the SecurityPersonalizer sketch. Secrets are stored in eeprom for all software based security features (including rfm69 encryption).

    There are many more things you can tweak using defines and we've tried to include most of them in relevant examples. The MyConfig.h/keywords.txt shows you the full list of defines available.

  • Hi,

    How does this work when your gateway also have local sensors? I tried to merge the Humidity sensor (DHT11) with the SerialGateway but it seems that presentation is not called after uploading the sketch. This is what I have:

    void setup() { 
      // Setup locally attached sensors
      metric = getConfig().isMetric;
    void presentation() {
     // Present locally attached sensors 
     sendSketchInfo("My Gateway", "1.0");
     present(CHILD_ID_HUM, S_HUM);
     present(CHILD_ID_TEMP, S_TEMP);

    And the output is:

    0;255;3;0;14;Gateway startup complete.
    0;255;3;0;9;No registration required
    0;255;3;0;9;Init complete, id=0, parent=0, distance=0, registration=1

    If I put the "present" lines at the setup() then I got the expected lines:

    0;255;3;0;14;Gateway startup complete.
    0;255;3;0;11;My Gateway
    0;255;3;0;9;No registration required
    0;255;3;0;9;Init complete, id=0, parent=0, distance=0, registration=1

    Is this expected or I missed something? I'm trying to use this gateway with homeassistant and it seems that homeassistant expect those presentation lines. There's a issue with the use of node "0" id too, but i should leave it to another topic.

  • Maybe related to this problem?

    My gateway does the same. No presentation, but sending data.

  • The API looks very clean and simple, I look forward to use it more.
    Does Arduino/MySensors uses C++ features (namespaces?) to prevent name collision? In typical C projects I've seen the functions all beginning with some prefix (mysensors_).

  • @rollercontainer Where should the "if (presentation).." be? At the setup()?

  • Mod

    @chrlyra there is no such thing as if(presentation)...
    The presentation function implementation can be anywhere in your sketch.

  • @Yveaux rollercontainer pointed to this issue:, where hek asked him to add two lines of code, the first one being "if (presentation)".

  • Mod

    @chrlyra That's what happens if you deviate from the topic... Anyway, thanks for the hint!

  • Great work ! This version looks a lot cleaner and the support for the RFM69 is more integrated. Thanks for that. One thing I'm missing and that's the specification of the encryption key for the RFM69. This was done in version 1.5.x by a user defined 16 bytes string. Now i see only a #define MY_RFM69_ENABLE_ENCRYPTION.
    How and where is the key specified ? How does this make my setup unique ?


  • Hardware Contributor

    If I remember well, it is handled by SecurityPersonalizer.ino It is sketch for signing options, and i think you can set/generate your rf aes key there. It store it in eeprom. Then you upload the new sketch with encryption define enabled. For me it's ok, as i use signing which needs to use the personalizer.
    I think this works like this, not sure as i have not enabled encryption yet. Am I right @Anticimex ?

  • Contest Winner

    @scalz is correct. Details are in the doxygen documentation for usage. Link is on the GitHub readme. Look under the signing module there.

  • @Anticimex
    Thanks, I got it working. By setting it to "soft" this sketch writes all key's to eeprom and will not look for a hardware siging module. The RFM69 uses the EAS key for encryption. I defined my own key again in the sketch.
    Nice solution !

  • Contest Winner

    @Rolo6442u precisely. Glad to hear that the docs are helping 🙂 and thanks!

  • How can i call the process() inside a while in the loop() ?


  • @pascalgauthier

    I think the function "wait()" might be useful. It is like a sleep, but now it calls "process()"

  • @nielsokker said:


    I think the function "wait()" might be useful. It is like a sleep, but now it calls "process()"

    I was thinking of using it with wait(0) but I was wondering if there was any way to call the process directly.

  • @pascalgauthier

    I'm not sure. I think the developers will know.

  • Hardware Contributor

    @pascalgauthier why do you need to call process ? It's already done internally by the lib. Or is it for inside some longtime loop? you still can use process but now it's _process()
    Wait is not the same as sleep.
    Wait : wait for a time and call _process
    sleep: does not call _process. it sleeps. for a time if set

  • @scalz
    Because i have while() that increment motion detected in a 30sec timeframe. And i would like to be sure that i'm not missing any cmd from the gateway. Do i need to define any additional library to use the _process() ?

  • Hero Member

    @pascalgauthier I would recommend making your while loop non-blocking i.s.o. hacking into a MySensors function.

  • Hardware Contributor

    yes it's better non blocking. for non blocking it's better to use "if" like. for beginning, I advise you to look at "blink without delay" concept. then learning a bit how a state machine works etc...could be useful to you. but it's a bit more advanced, or not..

  • @scalz @AWI

    Thanks for your help ! 🙂

  • Little bit confused. reading through the release notes...

    Deprecated variables: V_DIMMER (use V_PERCENTAGE), V_HEATER (use V_HVAC_FLOW_STATE), V_LIGHT (use V_STATUS)

    Now back to the API page for 2.0...

    S_DIMMER	4	Dimmable device of some kind	V_STATUS (on/off), V_DIMMER (dimmer level 0-100), V_WATT


  • And if my loop statement consists only of

    void loop() 
    { gw.process(); }

    Rewrite like
    void loop() { }

    or exclude loop completely?

  • Mod

    @moskovskiy82 said:

    Rewrite like
    void loop() { }

    That's correct

  • Mod

    @moskovskiy82 said:


    The release notes (as I added this statement 😉 )

  • Dear all, I'm a bit lost.
    I upgraded the library in Arduino to 2.0.0 and now I am having big problems.

    I downloaded the sketch for the relay from the MySensors website:
    but I suppose this is still for 1.5

    I tried to modify the sketch as suggested - I do not receive any compiling error, but the skectch simply does not do anything. If I use the "monitor" in Arduino IDE, I do not see anything 0_1469262004446_RelayActuator2.ino

    There must be something fundamentally wrong in my code, can anyone help?

  • Mod

    @Maurizio-Collu the examples for 2.0 are included in the library. They can be opened directly fromthe Examples menu in the Arduino IDE. It is also possible to fetch the examples from github, see For the relay example.

  • Hero Member


    You have a few mistakes in your sketch, Download the V2 sketch that @mfalkvidd has pointed you to and compare the two side by side. you will soon see where you have gone wrong. don't forget you will need to update your gateway to V2 as well, a version 1.5 gateway will not connect with a version 2 node.

  • @mfalkvidd @Boots33

    Thanks a lot, I knew I was missing something basic. For the newbies like me, it would be good to mention this somewhere (if you have not done so already and I missed it).

    In the Home Assistant website it is mentioned that they only support 1.4 and 1.5. I'm trying with 2.0.

    Thanks Again

  • Plugin Developer


    2.0 should work with home assistant, but all new features of 2.0 are not supported yet. WIP.

  • I'm trying to upgrade my gateway to 2.0, but every time I go to upload, I get a 'error' not in sync.

    I'm using just a standard nano w/ NRF24.

    Note, my hardware profile is set properly to nano, 328p and proper com.

    I restart app, and switched to my APM hardware profile and loaded my new 2.0 sensor code into my new APM node (DHT11 + motion) and was able to upload no problem.

    Is there something i'm missing for the gateway?


  • Admin

    Are you able to upload some other sketch to the nano?
    Or has something bad happen to the FTDI chip on your nano perhaps?

  • Just for clarification. V2.0 gateway (MQTT client esp8266) - will it work with the 1.5/1.6 sensors? Or everything needs to be flashed as soon as possible?

  • @hek it's actually a close nano with an FTDI board connected via serial inputs. I had this directly connected to my Vera, and communication with my old sensors was working just fine.

    EDIT: Fixed. All in all, it was user error. I was trying to connect through FTDI adapter. I unplugged FTDI board, connected USB directly to nano clone, and upload worked fine.

    Do I need to update mysensors plugin as well on Vera UI5?

  • Admin

    @rchamp said:

    Do I need to update mysensors plugin as well on Vera UI5?

    No, shouldn't be necessary.

  • Admin

    @moskovskiy82 said:

    Just for clarification. V2.0 gateway (MQTT client esp8266) - will it work with the 1.5/1.6 sensors?

    You could try, but the recommendation is to update the nodes as well.

  • @martinhjelmare
    Thanks Martin.

    I uploaded the GatewaySerial to the arduino working as gateway, but if I upload the sketch and I open the monitor, I obtain this error:

    0;255;3;0;9;Starting gateway (RNNGA-, 2.0.0)

    What does it mean?

  • @martinhjelmare
    Plus, when starting home assistant, I get this error

    16-07-26 23:03:44 homeassistant.bootstrap: Error during setup of component mysensors
    Traceback (most recent call last):
    File "/usr/local/lib/python3.4/dist-packages/homeassistant/components/", line 62, in setup_gateway
    OSError: illegal IP address string passed to inet_aton

    During handling of the above exception, another exception occurred:

    Traceback (most recent call last):
    File "/usr/local/lib/python3.4/dist-packages/homeassistant/", line 150, in _setup_component
    if not component.setup(hass, config):
    File "/usr/local/lib/python3.4/dist-packages/homeassistant/components/", line 109, in setup
    device, persistence_file, baud_rate, tcp_port)
    File "/usr/local/lib/python3.4/dist-packages/homeassistant/components/", line 73, in setup_gateway
    File "/home/pi/.homeassistant/deps/mysensors/", line 326, in init
    persistence_file, protocol_version)
    File "/home/pi/.homeassistant/deps/mysensors/", line 40, in init
    self.const = _const
    UnboundLocalError: local variable '_const' referenced before assignment

  • Plugin Developer


    Regarding the error in home assistant, that's a bug, due to specifying mysensors version other than 1.4 or 1.5. Use 1.5 and you should be fine. The bug is fixed in the dev branch of pymysensors and will be fixed in home assistant when real mysensors 2.0 support is merged. WIP.

    Please post home assistant topics in the home assistant category under controllers. This is off topic in this thread.

  • Plugin Developer

    @Maurizio-Collu said:

    Thanks Martin.

    I uploaded the GatewaySerial to the arduino working as gateway, but if I upload the sketch and I open the monitor, I obtain this error:

    0;255;3;0;9;Starting gateway (RNNGA-, 2.0.0)

    What does it mean?

    @tekka knows this best, and he wrote a post explaining some of those messages here:

  • @martinhjelmare Thanks a ot.
    Is there any guide/manual where all these messages are explained?

    Plus, is there anywhere written what all these terms mean?

    TSP:MSG:SEND 255-255-0-0 s=255,c=3,t=3,pt=0,l=0,sg=0,ft=0,st=ok:

    Kind Regards

  • Mod

    @Maurizio-Collu do you mean except the link martinhjelmare provided?

  • @mfalkvidd Yes, basically this part (I'm sure it is explained somewhere, but I can't find where)

    255-255-0-0 s=255,c=3,t=3,pt=0,l=0,sg=0,ft=0,st=ok:

    SOrry for my newbieness...

  • Admin

    @Maurizio-Collu Yes, the doc is in preparation, the meaning of these messages is described here (this is a PR that harmonizes the log message and will be pushed to 2.0.1).

    In brief:

    TSP:MSG:SEND 255-255-0-0 s=255,c=3,t=3,pt=0,l=0,sg=0,ft=0,st=ok:

    TSP:MSG:SEND refers to message sending function in the transport state machine

    255-255-0-0 is the routing information, i.e. sender-last-next-destination


    • s=sensor ID (255 = internal)
    • c=command (3 = C_INTERNAL)
    • t=type (3 = I_ID_REQUEST)
    • pt=payload type (0 = P_STRING)
    • l=message length (0)
    • sg=signature flag (0 = not signed)
    • ft=failed transmission counter (0 = no failed uplink transmission at this* oint)
    • st=send status (OK)
    • : actual message (empty)

    => Your node has no assigned ID (=255) and is requesting a new ID from the controller.

    Please refer to the serial protocol or API for additional information.

    Good luck!

  • Hi,
    I was trying to implement the irrigation controller but realized that was not migrated to MySensors 2.0.
    I followed the instructions provided in the first post and arrived to a version that compiles with no errors. Nonetheless, as I am newbie, I would appreciate if someone could review some changes that I am not sure about. Those changes are related with the original sketch which has direct calls to process() in several while statements. First I tried to change the process() with _process() but several errors appeared, so finally I removed all the calls to process() but am not sure. I have the modified code here IrrigationController.ino in which I commented the lines added / deleted / modified. Any help / direction would be greatly appreciated.

  • Hero Member


    The sketches that require external libraries are not included in the V2 install anymore but they are available here in the new V2 format. You will find the irrigation sketch there.

  • @Boots33 Great! Thank you for the quick response and the URL. I took that version. Just wanted to let you know that to successfully compile it was needed to remove the #include <LiquidCrystal.h> and probably an update to that sketch would be needed at Github respository.
    Thank you again!

  • Hero Member

    @pndgt0 That may be because you do not have the LiquidCrystal library installed. They have the external libraries there as well

  • This post is deleted!

  • I built a 2.0 MQTT gateway and am experimenting with a sensor using 1.5 library. I can see incoming data in the serial monitor, but the data is a bit different then when I was using the 1.5 MQTT gateway. In openhab I used this:


    But now I must skip the V_Tripped part to make it work like this:


    Is this how it is supposed to be or do I have to make the sensor node 2.0 compatible first? I thought the payload is saved in the V_TRIPPED variable, but it doesn´t seem to work in the new 2.0 library. Pls advise-


    Ok, digged a bit deeper: if I understand it right, I don´t need "V_TRIPPED" or any other value in my controllers code (which is openhab actually) anymore but still in my sensor node code of course. So the gateway will transform "V_Tripped" into sub-typ "16". Correct? So all I´ll have to change is my openhab code, right?

  • Mod

    @siod correct. The conversion of value code to text has been removed in the 2.0.0 implementation, so now the raw values codes are reported in the topic.

Log in to reply

Suggested Topics

  • 103
  • 3
  • 171
  • 183
  • 1075
  • 58
  • 162
  • 52