EV_TXDONE and transmission complete

[terrillmoore]

It's very easy to be confused by EV_TXDONE when writing code that sends uplinks, especially when sending back-to-back uplinks or sending at fixed periods that are short relative to network times. In sorting out issues, I came across this topic a lot. For example, #588 (comment)

1. The LMIC (as of v3.2) really is compliant with LoRaWAN. In addition, it reliably receives and processes downlink MAC control frames. (Before v3.2, any MAC control downlinks were largely ignored, or not handled compliantly)

2. Networks try to manage device transmit power, and so they send downlinks a lot more than you might expect. These downlinks require responses.

3. Downlinks are sent (and processed) in response to uplinks.

4. EV_TXDONE has never meant that the LMIC was idle; it only means that the work for transmitting user data is complete (including any associated RX downlink windows). It might mean that the LMIC is idle. EV_TXDONE is necessary for the LMIC to be idle, but it's not sufficient.

5. If the network sends you a downlink, the LMIC is not idle when it reports EV_TXDONE; it's already sending its uplink response. The LMIC cannot accept a new message until it's finished sending the uplink.

6. Furthermore, after sending the uplink, the LMIC must open another downlink window. That downlink window can contain another message, which might require another response.

7. As a practical matter, then, the application must inspect the LMIC state to know whether the LMIC is idle. The network can keep the LMIC busy for an arbitrarily long period of time. If your program doesn't cater for this, it is incorrect and can be forced to fail by a broken or malicious network. (This problem is probably not unique to the LMIC but is likely to manifest in different ways in different LoRaWAN stacks, depending on implementation strategy.)

8. If you try to transmit while the uplink path is busy, the send attempt will return an error code. The examples are not good about checking for this. (In older versions, the send APIs would silently fail, or silently malfunction.)

9. If you put the CPU to sleep while the LMIC is not idle, when you wake up, things are not going to be right in the LMIC.

Consequences:

1. Avoid using LMIC_setTxData() and LMIC_setTxData_strict(), because they don't return error status - you have no way to know if they worked. Instead use LMIC_setTxData2(), LMIC_setTxData2_strict(), LMIC_sendWithCallback() or LMIC_sendWithCallback_strict(). Footnote: older apps that used LMIC_setTxData() typically checked the flags in LMIC.opmode. But this is a bad idea, because when the LMIC is refactored to have a proper FSM, LMIC.opmode will necessarily change or go away entirely.

2. Check for errors when you try to transmit, and recover. The LMIC will not post a completion (EV_TXDONE) if the transmit didn't launch.

3. After calling one of the transmit APIs, avoid putting the CPU to sleep unless you know that the LMIC is not busy managing the link. Find out whether a given sleep interval is safe by calling the LMIC API os_queryTimeCriticalJobs(). Pass it how long you would like to sleep, in ostime_t ticks; it will return non-zero if there are time-critical jobs in the interval, and zero otherwise.

[oseiler2]

Thanks for the detailed explanation, that's very helpful.

Would it be possible to add a method to query the time to the next time critical job, instead of having to call os_queryTimeCriticalJobs() with artificial timeframes?
I've had a stab at this - apologies if I'm getting this wrong:
#641

[terrillmoore]

I agree, it's probably a good idea. I don't remember why I didn't add this before -- there was a reason, but it's not coming to me, and after writing the above, I agree with your response.

I'm still on deadline for something else, but I'll try to give feedback on your PR this weekend.

[oseiler2]

Any updates on this? I appreciate that you'll be busy - if there's anything I can do, please let me know.