Cellular: Provide API to restart cellular device

[RedaMaher]

This API will restart the cellular device and its state machine and will try to reconnect again.
It can be used from error recovery which an error happened in the cellular device
This pull request depends on PR #11154 and should be merged after it.

Description

Pull request type

[x] Fix
[ ] Refactor
[ ] Target update
[ ] Functionality change
[ ] Docs update
[ ] Test update
[ ] Breaking change

Reviewers

@AriParkkila

Release Notes

[ciarmcom]

@Reda-RM, thank you for your changes.
@AriParkkila @ARMmbed/mbed-os-wan @ARMmbed/mbed-os-maintainers please review.

[AriParkkila]

Should check if a context has called connect and re-connection is really required.
In async mode should wait for DISCONNECTED events before calling connect().

[RedaMaher]

@AriParkkila How can we know if connect() was called before? Should I use is_connected() before shutting down the device?
Regarding the async mode I thought it will be handled through the connect() itself through the event queue. Can we change the mode temporary to synchronous mode here and then return it back after connecting? is there a better way for both points?

[kjbracey]

Why does this need to be a new API method? Is it not just a series of calls to existing APIs?

Having an API like this seems like it just raises too many questions about what exactly it does - you'd have to end up specifying the exact sequence of sub-calls it makes, which then makes it feel like it may as well just be an example code snippet, or external library helper.

And then you'd find yourself adding all the blocking/non-blocking variations, and events...

Generically, I would expect the generic "disconnect" followed by "connect" on a NetworkInterface to have the effect of resetting it for any type of network device. That would allow this sort of thing to be done portably. If doing that for a cellular NetworkInterface doesn't achieve that, maybe that should be reconsidered. (Is there an issue about it not auto-powering down?)

[RedaMaher]

@kjbracey-arm I agree with you that using disconnect then connect is better to reset the network interface. However this is not the case in cellular device so I introduced this new API. If you are going to consider restarting the cellular device and its state machine in disconnect API then no need at all for the new one.
issue #10912 raises this PR

[0xc0170]

This pull request depends on PR #11154 and should be merged after it.

It was merged. @ARMmbed/mbed-os-wan please review

[AriParkkila]

disconnect then connect is better to reset the network interface

Mbed OS API description for disconnect() is briefly "Disconnect from the network.". Should that read as to disconnect just from a packet network (that is current implementation) or also from a cellular network? Do you mean that disconnect() should power down the modem so that applications could reset the network interface simply by calling disconnect/connect?

[0xc0170]

@Reda-RM Any comments for above questions?

[RedaMaher]

disconnect then connect is better to reset the network interface

Mbed OS API description for disconnect() is briefly "Disconnect from the network.". Should that read as to disconnect just from a packet network (that is current implementation) or also from a cellular network? Do you mean that disconnect() should power down the modem so that applications could reset the network interface simply by calling disconnect/connect?

If we would like to do not add special API for cellular interfaces then I think "disconnect() should power down the modem so that applications could reset the network interface simply by calling disconnect/connect". If this fine with you, I will update the PR to make disconnect() powers down the modem

[0Grit]

@trowbridgec Make sure you put your 2 cents in.

[vidavidorra]

I don't think disconnect should power down. When I disconnect I only want to disconnect from the network, either cellular or packet (as it's now). That way I can leave the modem powered on and save some time in the next connect.
I don't see a proplem doing multiple API calls to power down and reset the modem as long as it's properly documented. Another option IMHO would be to power down the modem in the reset call.

[RedaMaher]

We may make disconnect() accept a boolean parameter which choose whether to power down the modem and shutdown the cellular interface or to just disconnect from the network. What do you think?

[vidavidorra]

We may make disconnect() accept a boolean parameter which choose whether to power down the modem and shutdown the cellular interface or to just disconnect from the network

@Reda-RM That would work too. The point I wanted to make is that IMHO there still should be a way to just disconnect from the network and what you've described above would achieve that too.

[trowbridgec]

My two cents is that PSM applications should be taken into account when considering the functionality of connect()/disconnect().

Should I be able to call disconnect() on the cellular device and preserve PSM state?

Related issues:

• Cellular PSM - Wake Module Provisions? #10737
• Quectel BG96 Wake from PSM #11088

[0Grit]

Continuing what @trowbridgec typed above; Additional consideration in documentation should also be given for how to manage Pelion client when an api like this is called as well as in PSM scenario's.

[0xc0170]

Note, we are close to the 5.14 code freeze. This needs update asap to be in 5.14 otherwise will move to the next minor version

[lauri-piikivi]

Hi alls,

I do not want this in connect/disconnect even with a bool parameter. Cellular device can have multiple connections, and being able to just disconnect is one way to use it as stated. Similarly, there is actually 2 stages in cellular devices, attach and connect.

I do not think any of the current intefaces reset when disconnect is called -- if the reset here means any sort of HW level reset. If the justification is general operation on any interface, this would need to be implemented on all interfaces and drivers. This is a big change.

Disconnect will invalidate PSM -- PSM maintains the network addressing, and disconnect changes that when the PDP context is closed. So PSM will be affected, network signalling is caused.

So in summary I propose no changes to NetworkInterface. And it should not be specific for cellular device -- the separate calls should be used because they do provide the flexibility needed.

[RedaMaher]

If we do not like to modify the disconnect, should we at least make shutdown() has a parameter to power down the modem? then to reset the connectivity (in case of modem hanged for example) we will call shutdown(power_off_modem=true) then connect().

[0xc0170]

I removed 5.14 label, as this is not ready yet

[AriParkkila]

@Reda-RM CellularDevice API has soft_power_off to power down the modem after calling shutdown.

In general, init and shutdown are to be implemented with the standard (AT) commands and thus they should be common to most modems, soft_power_on/off is to power the modem and also force reset when not responsive, and hard_power_on/off is (I think) intended for device power domains.

[RedaMaher]

I will close this PR and individual APIs should be used instead to reset the network interface. May be a documentation is needed for the reset sequence.