💬 MySensors Library - v2.x

[alowhum]

I was working on creating the 'ultimate header' for all my devices. The documentation page that this thread refers to has left me with a lot of questions. Here's a list of what I think I understand, and the things that I don't.

• MY_PARENT_NODE_ID. I suspect this refers to the node ID of the gateway, which would make it 0. Or can it also be used to manually point a specific repeater?
• MY_PARENT_NODE_IS_STATIC. What is this? When would this matter? If I set a parent node ID manually, isn't it implied that it doesn't ever change already?
• MY_REPEATER_FEATURE. Perhaps nice to explain that there is no downside to turning this on for every node (as long as the nodes don't run on batter and their code is non-blocking).
• MY_DEBUG. perhaps mention that there is a tool to translate these into human readable form? Perhaps create a page with the most common errors and what they mean?
• MY_INCLUSION_MODE_FEATURE. If I understand correctly, if you enable this it means that controller, and not the gateway itself, will be given control over whether or not new devices may be added to the network.
• MY_INCLUSION_BUTTON_FEATURE. If I understand correctly, this is used by gateway nodes only, and means that you have to press a button on the gateway device before it will accept new nodes into the network. You then set the button's pin number with this: #define MY_INCLUSION_MODE_BUTTON_PIN
• MY_SIGNING_SOFT. Signing is like a signature: it allows a node to say "this data really came from me". It protects your network from impostors. See also "my simple security. The "soft" version does this with code only. To do this well it needs a good source of random numbers, and one way of doing this is to listen to the noise on an arduino pin. MY_SIGNING_SOFT_RANDOMSEED_PIN allows you to set that pin.
  You can also buy devices that aid in this signing process. See: MY_SIGNING_ATSHA204
• MY_RF24_ENABLE_ENCRYPTION. Encrypts the communication so that your neighbour can't listen in. See also "my simple security.
• MY_RF24_CE_PIN. While you can't change all the pins that connect the radio to the Arduino, there are some that you can change. This is one of them.
• MY_RF24_CS_PIN. This is the other.
• MY_RF24_DATARATE. You can set at which speed the NRF24 radio communicates. Important to note is that this is all or nothing: all devices in the network should work at the same speed. Lower speed will create a more 'coarse' signal, and this will help improve wireless range. As most MySensors networks only send a little bit of data once in a while, a slow speed should be fine. You can try:
  #define MY_RF24_DATARATE RF24_1MBPS // fast
  #define MY_RF24_DATARATE RF24_250KBPS // slow
• MY_RF24_BASE_RADIO_ID ?
• MY_SOFTSPI (et all) . Perhaps this can be used to use any pin on the Arduino to communicate with the radio. I don't know if this requires another Arduino library to support this.
• MY_CORE_ONLY. I have no idea what the difference is. @Anticimex says: "core functions are things like the HAL and debug logging functionality. Framework means all the presentation message transmissions and handshaking. Basically, MY_CORE_ONLY allow you to leverage the functionality provided by the library without having the library execute things out of your control.". If you have to ask, then probably just don't use it :-)
• MY_CORE_COMPATIBILITY_CHECK. As far as I can tell MySensors is remarkable backwards compatible: your gateway can be newer than your nodes. So I'm not sure when you would want to use this.
• MY_TRANSPORT_SANITY_CHECK Once in a while checks that your radio is actually working. I don't know how you could use this. Perhaps if you see a lot of failures, and connection is temporarily working, then you could inform the controller about the radio slowly dying? More here.
• MY_TRANSPORT_DISCOVERY_INTERVAL_MS. As far as I understand, the Gateway will once in a while shout "who is there" into the air. All the nodes can then respond. This allows new nodes to be included, even if something went wrong during the initial presentaiton phase? Perhaps it is also used to detect that some devices are no longer on the network? And then it can shrink the routing table? Perhaps this is like a server-side command to ask all nodes to do a 'sendHeartbeat();' ?
• MY_TRANSPORT_UPLINK_CHECK_DISABLED. When you start a node, it will check if it can talk with the gateway. This skips that check. I suspect that this will then not be activated: if(isTransportReady()){ // do something }.
• MY_TRANSPORT_MAX_TX_FAILURES. How often it will try to connect with the radio hardware? What happens when it fails a number of times? Does it give up? Retry later? What is "SNP"?
• MY_TRANSPORT_WAIT_READY_MS. Very useful. You can tell a node to try connecting to the gateway for X seconds, but if it fails, it should just carry on. I usually set this to 10000 so that it will try connecting to the network for ten seconds, and then just continue starting the node. The default is 0, meaning that if a node can't connect to the gateway it will never reach the loop() portion of your code!
• MY_SMART_SLEEP_WAIT_DURATION_MS. Apparently MySensors has a 'smart sleep' feature, intended to save battery. If I understand correctly, when enabled, the nodes will sleep most of the time, and then wake up once in a while to see if the gateway has any messages for them. The node makes an agreement with the gateway about how often it will wake up, when, and for how long, beforehand. I wonder how it's different from: MY_SMART_SLEEP_WAIT_DURATION
• MY_NODE_LOCK_FEATURE. If suspicious activity is detected the node will 'lock down'. I don't know what suspicious activity is, how it would be detected, and what a 'lock down' entails. Probably not sending any messages for a while?
• MY_NODE_UNLOCK_PIN. Apparently nobody on the forum has every posted anything about this. It seems you can 'unlock' a 'locked down' node by pressing a physical button on it?
• MY_NODE_LOCK_COUNTER_MAX Probably how often suspicious activity can happen before it enters lock-down? I wonder, does this count ever get lower? More importantly: if I never use this feature (who does?), can I avoid it using storage/memory in my nodes?
• MY_WIFI_SSID (etc). I suspect a MySensors gateway can connect to your home network if you provide it with the necessary details.
• MY_GATEWAY_MAX_CLIENTS. Apparently there is a server mode. Not sure what that means.
• MY_SPIFLASH_SST25TYPE This is probably used with over the air (OTA) flashing of nodes.

On top of that it seems there are some more commands (that are not in the documentation?). Thanks to @mfalkvidd for this list.

MY_BAUD_RATE
MY_CORE_ONLY
MY_CORE_MIN_VERSION
MY_CORE_VERSION
MY_CRITICAL_SECTION // Something to do with NRF5 support?
MY_DISABLE_RAM_ROUTING_TABLE_FEATURE // I really want to know how routing tables can be managed/optimised for my situation.
MY_DISABLE_REMOTE_RESET // Whether or not the node can be reset from a controller? Is this useful for FOTA procedures?
MY_DISABLED_SERIAL
MY_INDICATION_HANDLER // Something about an AVR bug?
MY_RX_MESSAGE_BUFFER_FEATURE ? It's optional. This adds an incoming messages buffer to your node (but only for NRF24 devices, and you need so set IRQ)". Useful for nodes that receive a lot of messages from the controller? What happens if you have a buffer for 5 messages, and a 6th arrives? (Ah, "The variable transportLostMessageCount will be increased for each lost message.") Does a node that acts as a gateway or repeater have this enabled?
MY_SERIAL_OUTPUT_SIZE ?
MY_SLEEP_NOT_POSSIBLE ?
MY_SMART_SLEEP_WAIT_DURATION
MY_SPLASH_SCREEN_DISABLED
MY_WAKE_UP_BY_TIMER ? Probably for smart sleep?
MY_CORE_COMPATIBILITY_CHECK ? What does this do? What is an 'incompatiblity?' And what happens if there is one? When do I want to use this?
MY_DEBUG_VERBOSE_TRANSPORT
MY_NODE_ID
MY_PARENT_NODE_ID
MY_PARENT_NODE_IS_STATIC
MY_PASSIVE_NODE
MY_RAM_ROUTING_TABLE_FEATURE
MY_REGISTRATION_CONTROLLER ? Unknown, very little on the forum
MY_REGISTRATION_DEFAULT ?
MY_REGISTRATION_FEATURE
MY_REGISTRATION_RETRIES
MY_REPEATER_FEATURE
MY_ROUTING_TABLE_SAVE_INTERVAL_MS // How often the ram routing table is saved to the EEPROM
MY_SIGNAL_REPORT_ENABLED // Disabling the signal report can save a lot of storage space if you use security features? I can't find anything about what it actually does. I did find that in a future version of MYSensors it will probably be disabled by default. Also, I can only find code that refers to RFM69/RFM95 devices, so it's probably not useful for NRF24/52 devices anyway? Oddly, there's also the opposite command: #define MY_DISABLE_SIGNAL_REPORT
MY_SLEEP_TRANSPORT_RECONNECT_TIMEOUT_MS ? How often it will try to reconnect to the gateway if it fails? Sounds useful. What's the default I wonder.
MY_SMART_SLEEP_WAIT_DURATION_MS
MY_TRANSPORT_CHKUPL_INTERVAL_MS // "interval to re-check uplink". Sounds important and useful.
MY_TRANSPORT_DISCOVERY_INTERVAL_MS // How often the gateway broadcasts the "hello, anybody there? say hi!" message. Default is once every 20 minutes.
MY_TRANSPORT_MAX_TSM_FAILURES // TSM is the "transport state machine". So this probably has something to do with the radio working or not. Apparently the node will try operating the radio 7 times, and then enter a 'failure mode'. In this mode it will try using the radio less often (probably important if you have a battery powered node, and the radio breaks down. You don't want it to drain the battery.)
MY_TRANSPORT_MAX_TX_FAILURES
MY_TRANSPORT_SANITY_CHECK // "Setting MY_TRANSPORT_SANITY_CHECK enables regular radio HW checks (i.e. verify radio register settings), the check interval is set via MY_TRANSPORT_SANITY_CHECK_INTERVAL_MS. This check is solely HW-based and does not verify uplink status or similar." Whether or not to check if the radio hardware is OK once in a while.
MY_TRANSPORT_SANITY_CHECK_INTERVAL
MY_TRANSPORT_SANITY_CHECK_INTERVAL_MS
MY_TRANSPORT_STATE_RETRIES ?
MY_TRANSPORT_STATE_TIMEOUT_MS
MY_TRANSPORT_TIMEOUT_EXT_FAILURE_STATE_MS
MY_TRANSPORT_TIMEOUT_FAILURE_STATE_MS
MY_TRANSPORT_UPLINK_CHECK_DISABLED
MY_TRANSPORT_WAIT_READY_MS
MY_DEBUG
MY_DEBUGDEVICE // Apparently you can redirect get debug information to go somewhere else than the normal Serial output. Perhaps send it to another pin via software serial?
MY_DEBUG_VERBOSE_GATEWAY
MY_SPECIAL_DEBUG
MY_DEBUG_OTA
MY_DEBUG_OTA_DISABLE_ACK
MY_DEBUG_VERBOSE_OTA_UPDATE
MY_DEFAULT_ERR_LED_PIN
MY_DEFAULT_LED_BLINK_PERIOD
MY_DEFAULT_RX_LED_PIN
MY_DEFAULT_TX_LED_PIN
MY_INCLUSION_MODE_FEATURE
MY_INCLUSION_BUTTON_FEATURE
MY_INCLUSION_MODE_BUTTON_PIN
MY_INCLUSION_MODE_DURATION
MY_INCLUSION_LED_PIN
MY_OTA_FIRMWARE_FEATURE
MY_OTA_FLASH_SS
MY_OTA_FLASH_JDECID
MY_OTA_LOG_RECEIVER_FEATURE
MY_OTA_LOG_SENDER_FEATURE
MY_OTA_USE_I2C_EEPROM
MY_SPIFLASH_SST25TYPE
MY_WITH_LEDS_BLINKING_INVERSE
MY_DEBUG_VERBOSE_SIGNING
MY_ENCRYPTION_SIMPLE_PASSWD
MY_NODE_LOCK_FEATURE
MY_NODE_UNLOCK_PIN
MY_NODE_LOCK_COUNTER_MAX
MY_SECURITY_SIMPLE_PASSWD
MY_SIGNING_ATSHA204
MY_SIGNING_ATSHA204_PIN
MY_SIGNING_NODE_WHITELISTING
MY_SIGNING_SIMPLE_PASSWD
MY_SIGNING_SOFT
MY_SIGNING_SOFT_RANDOMSEED_PIN
MY_SIGNING_REQUEST_SIGNATURES
MY_SIGNING_WEAK_SECURITY
MY_VERIFICATION_TIMEOUT_MS
MY_HW_HAS_GETENTROPY
MY_GATEWAY_TINYGSM
MY_GSM_APN // apparently there is some kind of built-in GSM support?? Or does this connect to the TinyGSM library, and thus requires that library to also be included?
MY_GSM_BAUDRATE
MY_GSM_PIN
MY_GSM_PSW
MY_GSM_RX
MY_GSM_SSID
MY_GSM_TX
MY_GSM_USR
MY_SOFTSPI
MY_SOFT_SPI_MISO_PIN
MY_SOFT_SPI_MOSI_PIN
MY_SOFT_SPI_SCK_PIN
MY_DEBUG_VERBOSE_RF24
MY_RADIO_RF24
MY_RF24_ADDR_WIDTH
MY_RF24_BASE_RADIO_ID
MY_RF24_ENABLE_ENCRYPTION
MY_RF24_CE_PIN
MY_RF24_CHANNEL
MY_RF24_CS_PIN
MY_RF24_DATARATE
MY_RF24_IRQ_PIN
MY_RF24_PA_LEVEL
MY_RF24_POWER_PIN
MY_RF24_SPI_SPEED // What does this do I wonder.
MY_DEBUG_VERBOSE_NRF5_ESB
MY_NRF5_ESB_ADDR_WIDTH
MY_NRF5_ESB_BASE_RADIO_ID
MY_NRF5_ESB_CHANNEL
MY_NRF5_ESB_ENABLE_ENCRYPTION
MY_NRF5_ESB_MODE
MY_NRF5_ESB_PA_LEVEL
MY_NRF5_ESB_RX_BUFFER_SIZE
MY_NRF5_ESB_REVERSE_ACK_RX
MY_NRF5_ESB_REVERSE_ACK_TX
MY_RADIO_NRF5_ESB
MY_DEBUG_VERBOSE_RFM95
MY_RADIO_RFM95
MY_RFM95_ATC_MODE_DISABLED
MY_RFM95_ATC_TARGET_RSSI
MY_RFM95_ATC_TARGET_RSSI_DBM
MY_RFM95_CS_PIN
MY_RFM95_FREQUENCY
MY_RFM95_IRQ_NUM
MY_RFM95_IRQ_PIN
MY_RFM95_MAX_POWER_LEVEL_DBM
MY_RFM95_MODEM_CONFIGRUATION
MY_RFM95_POWER_PIN
MY_RFM95_RST_PIN
MY_RFM95_SPI_SPEED
MY_RFM95_TCXO
MY_RFM95_TX_POWER
MY_RFM95_TX_POWER_DBM
MY_RFM95_TX_TIMEOUT_MS
MY_RFM95_ENABLE_ENCRYPTION
MY_DEBUG_VERBOSE_RFM69
MY_DEBUG_VERBOSE_RFM69_REGISTERS
MY_IS_RFM69HW
MY_RADIO_RFM69
MY_RFM69_ATC_MODE_DISABLED
MY_RFM69_ATC_TARGET_RSSI_DBM
MY_RFM69_BITRATE_LSB
MY_RFM69_BITRATE_MSB
MY_RFM69_CS_PIN
MY_RFM69_CSMA_ADD_DELAY_BASE
MY_RFM69_CSMA_ADD_DELAY_COUNT
MY_RFM69_CSMA_LIMIT_DBM
MY_RFM69_CSMA_TIMEOUT_MS
MY_RFM69_DEFAULT_LISTEN_IDLE_US
MY_RFM69_DEFAULT_LISTEN_RX_US
MY_RFM69_ENABLE_ENCRYPTION
MY_RFM69_ENABLE_LISTENMODE
MY_RFM69_FREQUENCY
MY_RFM69_IRQ_NUM
MY_RFM69_IRQ_PIN
MY_RFM69_MAX_POWER_LEVEL_DBM
MY_RFM69_MODEM_CONFIGURATION
MY_RFM69_NETWORKID
MY_RFM69_NEW_DRIVER
MY_RFM69_POWER_PIN
MY_RFM69_RST_PIN
MY_RFM69_SPI_SPEED
MY_RFM69_TX_TIMEOUT_MS
MY_RFM69_TX_POWER_DBM
MY_RS485
MY_RS485_BAUD_RATE
MY_RS485_DE_PIN
MY_RS485_HWSERIAL
MY_RS485_MAX_MESSAGE_LENGTH
MY_RS485_SOH_COUNT
MY_GATEWAY_CLIENT_MODE
MY_GATEWAY_ENC28J60
MY_GATEWAY_ESP32
MY_GATEWAY_ESP8266
MY_GATEWAY_MQTT_CLIENT
MY_GATEWAY_SERIAL
MY_GATEWAY_W5100
MY_HOSTNAME
MY_INCLUSION_BUTTON_EXTERNAL_PULLUP // This probably tells MySensors that the pin to which the inclusion button is connected has an external resistor, and thus doesn't require the internal Arduino resistor to be pulled up too.
MY_MQTT_CLIENT_ID
MY_MQTT_CLIENT_PUBLISH_RETAIN
MY_MQTT_PASSWORD
MY_MQTT_PUBLISH_TOPIC_PREFIX
MY_MQTT_SUBSCRIBE_TOPIC_PREFIX
MY_MQTT_USER
MY_W5100_SPI_EN // The W5100 is an Ethernet chip?
MY_WIFI_SSID
MY_WIFI_BSSID
MY_WIFI_PASSWORD
MY_CONTROLLER_IP_ADDRESS
MY_CONTROLLER_URL_ADDRESS
MY_GATEWAY_MAX_CLIENTS ? Can we set how many nodes may connect? Or perpahs this is more about how many simultaneous IP connections to IP-based gateways may be made (ethernet/wifi gateways).
MY_GATEWAY_MAX_RECEIVE_LENGTH ? What does this do I wonder. I suspect it's for TCP/IP connections.
MY_GATEWAY_MAX_SEND_LENGTH ? What does this do I wonder
MY_IP_ADDRESS
MY_IP_GATEWAY_ADDRESS
MY_IP_RENEWAL_INTERVAL
MY_IP_RENEWAL_INTERVAL_MS
MY_IP_SUBNET_ADDRESS
MY_MAC_ADDRESS
MY_PORT
MY_USE_UDP
MY_ESP8266_SERIAL_MODE

One that was not in the list, but seems very useful:
MY_TRANSPORT_TIMEOUT_EXT_FAILURE_STATE

[Anticimex]

@alowhum well, based on my comment, in combination with your question, conclusion is: Do not use MY_CORE_ONLY ;)
Also, the list of undocumented defines contain at least one define I know to be documented: MY_ENCRYPTION_SIMPLE_PASSWD. And that documentation is here:
https://www.mysensors.org/apidocs/group__EncryptionSettingGrpPub.html#ga5161276ef64d05342dae2bdfc042e0bb

You will probably find a lot more documentation in there.

[alowhum]

@Anticimex Thanks!

Unfortunately the documentation there is often just as sparse. For example, I wanted to learn more about MY_DISABLE_RAM_ROUTING_TABLE_FEATURE. But it just says. "If defined, routing table will not be kept in RAM.".

That doesn't tell me anything about why and when I might choose to enable or disable this feature.

[mfalkvidd]

@alowhum to my knowledge, all but 8 of the MY_ keywords are documented. To document the remaining 8, https://github.com/mysensors/MySensors/issues/1107 was created.

Documentation can always be improved of course, and your feedback may make it easier what needs to be changed/added. I personally don't have enough knowledge to answer most of your questions though (except those that already have answers in the documentation).

[Anticimex]

@alowhum well, the documentation also links to another flag, MY_RAM_ROUTING_TABLE_FEATURE, which is documented as "If enabled, the routing table is kept in RAM (if memory allows) and saved in regular intervals." so it is pretty clear in my opinion that enabeling MY_DISABLE_RAM_ROUTING_TABLE_FEATURE will prevent the table from being cached in ram for faster lookup. But improvements are always welcome and since the documentation is inlined in code, pull requests can be made to improve it.

[alowhum]

@anticimex Thanks, but my point is that as a beginner I have so many questions.

• Being able to disable storing the routing table in memory.. implies that normally the routing table is stored somewhere else? In eeprom?
• How big is a routing table? What is in it? Does a node have a map of the entire network? Or does it only have a map of the nodes it's connected to? Or just the children it has if it's a repeater?
• What does the routing table do exactly?
• When is the routing table generated?
• When is it re-generated? For example, what happens when I add a new repeater in the middle of my house. Do all devices figure out there are faster routes somehow?
• What happens when a repeater is suddenly removed? How does the network 'heal' itself? To what degree does it heal itself? How long will it take for the network to heal itself?
• What is the advantage of having a routing table in memory? You mention faster lookup. Does this mean slow lookup could create problems? In what situations should I care about this? If a node is a repeater, should I prefer it to be in memory then?
• Does it matter if some nodes have it in memory, and others don't?

I have similar "so how does it actually work" questions in a lot of areas. MySensors has a lot of features, but it's not always easy to figure out what all the features do, why they were made, and how I can decide what feature to enable for certain use cases.

[alphaHotel]

There's a broken link in the reference for MY_OTA_FIRMWARE_FEATURE in the Configuration section above (https://www.mysensors.org/download/sensor_api_20#configuration). I believe the correct URL should be https://www.mysensors.org/about/fota.

[FlyingDomotic]

@alowhum said in 💬 MySensors Library - v2.x:

Being able to disable storing the routing table in memory.. implies that normally the routing table is stored somewhere else? In eeprom?

For simple network, with all nodes sending to gateway, this may just be ... nowhere, and systematically send to the destination node, without any routing.

You may also define static neighbor (like MY_NEIGHBOR_ID in the same spirit as MY_NODE_ID).

[mfalkvidd]

@alphahotel thanks for noticing. I have fixed the link.

[TheoL]

It might be me, but when I declare the receiveTime handler is stated in the documentation:

bool receiveTime(uint32_t ts);

I get an error. it should be:

void receiveTime(uint32_t ts) {
}

at least in the latest MySensors version

[nagelc]

: ) That looks right. I have not written a receiveTime function for years and have just been copying the one in MockMySensors over and over.