Skip to content

Commit a42aa44

Browse files
author
Ari Parkkila
committed
Cellular: Update API description to match better onboard_modem_api
1 parent 84216a5 commit a42aa44

File tree

16 files changed

+46
-26
lines changed

16 files changed

+46
-26
lines changed

features/cellular/framework/API/CellularDevice.h

Lines changed: 33 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -76,36 +76,61 @@ class CellularDevice {
7676
*/
7777
virtual ~CellularDevice();
7878

79-
/** Set cellular device power supply on.
79+
/** Sets the modem up for powering on
80+
* This is equivalent to plugging in the device, i.e., attaching power and serial port.
81+
* In general, hard_power_on and soft_power_on provides a simple hardware abstraction layer
82+
* on top of the modem drivers written for Mbed OS; they can be overridden
83+
* in a derived class to perform custom power controls in a particular board configuration.
84+
* In many boards this will be a no-op if there is no separate power supply control circuitry.
8085
*
81-
* CellularStateMachine calls hard_power_on, soft_power_on and init when requested to connect
82-
* if the modem is not responding.
86+
* @remark CellularStateMachine calls hard_power_on at first until successful,
87+
* then soft_power_on and init until the modem responds.
88+
* If you are not using CellularStateMachine then you need to call these functions yourself.
8389
*
8490
* @post You must call soft_power_on to power on the modem after calling hard_power_on.
8591
*
8692
* @return NSAPI_ERROR_OK on success
8793
*/
8894
virtual nsapi_error_t hard_power_on() = 0;
8995

90-
/** Set cellular device power supply off.
96+
/** Sets the modem in unplugged state
9197
*
92-
* CellularStateMachine disconnect does not shutdown or power off the modem.
98+
* This is equivalent to pulling the plug off of the device, i.e.,
99+
* detaching power and serial port.
100+
*
101+
* This puts the modem in the lowest power state.
102+
*
103+
* @remark CellularStateMachine disconnect or destruct does not shutdown or power off the modem,
104+
* but you need to do that yourself.
93105
*
94106
* @pre You must call soft_power_off to power off the modem before calling hard_power_off.
95107
*
96108
* @return NSAPI_ERROR_OK on success
97109
*/
98110
virtual nsapi_error_t hard_power_off() = 0;
99111

100-
/** Set cellular device power on, i.e. start the modem.
112+
/** Powers up the modem
113+
*
114+
* This is equivalent to pressing the "power button" to activate or reset the modem
115+
* and usually implemented as a short pulse on a dedicated GPIO signal.
116+
* It is expected to be present to make it possible to reset the modem.
117+
* The driver may repeat this if the modem is not responsive to AT commands.
118+
*
119+
* @remark CellularStateMachine calls this when requested to connect.
120+
* If you are not using CellularStateMachine then you need to call this function yourself.
101121
*
102122
* @post You must call init to setup the modem.
103123
*
104124
* @return NSAPI_ERROR_OK on success
105125
*/
106126
virtual nsapi_error_t soft_power_on() = 0;
107127

108-
/** Set cellular device power off.
128+
/** Powers down the modem
129+
*
130+
* This is equivalent to turning off the modem by button press.
131+
*
132+
* @remark CellularStateMachine disconnect or destruct does not shutdown or power off the modem,
133+
* but you need to do that yourself.
109134
*
110135
* @pre You must call shutdown to prepare the modem for power off.
111136
*
@@ -310,7 +335,7 @@ class CellularDevice {
310335
* For example, when multiple cellular modules are supported in a single driver this function
311336
* detects and adapts to an actual module at runtime.
312337
*
313-
* CellularStateMachine calls soft_power_on and init repeatedly when starting to connect
338+
* @remark CellularStateMachine calls soft_power_on and init repeatedly when starting to connect
314339
* until the modem responds.
315340
*
316341
* @return NSAPI_ERROR_OK on success

features/cellular/framework/targets/GEMALTO/CINTERION/GEMALTO_CINTERION.cpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ CellularDevice *CellularDevice::get_default_instance()
6767
{
6868
static UARTSerial serial(MBED_CONF_GEMALTO_CINTERION_TX, MBED_CONF_GEMALTO_CINTERION_RX, MBED_CONF_GEMALTO_CINTERION_BAUDRATE);
6969
#if defined (MBED_CONF_UBLOX_AT_RTS) && defined(MBED_CONF_UBLOX_AT_CTS)
70-
tr_info("GEMALTO_CINTERION flow control: RTS %d CTS %d", MBED_CONF_GEMALTO_CINTERION_RTS, MBED_CONF_GEMALTO_CINTERION_CTS);
70+
tr_debug("GEMALTO_CINTERION flow control: RTS %d CTS %d", MBED_CONF_GEMALTO_CINTERION_RTS, MBED_CONF_GEMALTO_CINTERION_CTS);
7171
serial.set_flow_control(SerialBase::RTSCTS, MBED_CONF_GEMALTO_CINTERION_RTS, MBED_CONF_GEMALTO_CINTERION_CTS);
7272
#endif
7373
static GEMALTO_CINTERION device(&serial);

features/cellular/framework/targets/GENERIC/GENERIC_AT3GPP/GENERIC_AT3GPP.cpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ CellularDevice *CellularDevice::get_default_instance()
4444
{
4545
static UARTSerial serial(MBED_CONF_GENERIC_AT3GPP_TX, MBED_CONF_GENERIC_AT3GPP_RX, MBED_CONF_GENERIC_AT3GPP_BAUDRATE);
4646
#if defined (MBED_CONF_GENERIC_AT3GPP_RTS) && defined(MBED_CONF_GENERIC_AT3GPP_CTS)
47-
tr_info("GENERIC_AT3GPP flow control: RTS %d CTS %d", MBED_CONF_GENERIC_AT3GPP_RTS, MBED_CONF_GENERIC_AT3GPP_CTS);
47+
tr_debug("GENERIC_AT3GPP flow control: RTS %d CTS %d", MBED_CONF_GENERIC_AT3GPP_RTS, MBED_CONF_GENERIC_AT3GPP_CTS);
4848
serial.set_flow_control(SerialBase::RTSCTS, MBED_CONF_GENERIC_AT3GPP_RTS, MBED_CONF_GENERIC_AT3GPP_CTS);
4949
#endif
5050
static GENERIC_AT3GPP device(&serial);

features/cellular/framework/targets/MultiTech/DragonflyNano/PPP/SARA4_PPP.cpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ CellularDevice *CellularDevice::get_default_instance()
4949
{
5050
static UARTSerial serial(MBED_CONF_SARA4_PPP_TX, MBED_CONF_SARA4_PPP_RX, MBED_CONF_SARA4_PPP_BAUDRATE);
5151
#if defined (MBED_CONF_SARA4_PPP_RTS) && defined (MBED_CONF_SARA4_PPP_CTS)
52-
tr_info("SARA4_PPP flow control: RTS %d CTS %d", MBED_CONF_SARA4_PPP_RTS, MBED_CONF_SARA4_PPP_CTS);
52+
tr_debug("SARA4_PPP flow control: RTS %d CTS %d", MBED_CONF_SARA4_PPP_RTS, MBED_CONF_SARA4_PPP_CTS);
5353
serial.set_flow_control(SerialBase::RTSCTS, MBED_CONF_SARA4_PPP_RTS, MBED_CONF_SARA4_PPP_CTS);
5454
#endif
5555
static SARA4_PPP device(&serial);

features/cellular/framework/targets/QUECTEL/BC95/QUECTEL_BC95.cpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,7 @@ CellularDevice *CellularDevice::get_default_instance()
9797
{
9898
static UARTSerial serial(MBED_CONF_QUECTEL_BC95_TX, MBED_CONF_QUECTEL_BC95_RX, MBED_CONF_QUECTEL_BC95_BAUDRATE);
9999
#if defined (MBED_CONF_UBLOX_AT_RTS) && defined(MBED_CONF_UBLOX_AT_CTS)
100-
tr_info("QUECTEL_BC95 flow control: RTS %d CTS %d", MBED_CONF_QUECTEL_BC95_RTS, MBED_CONF_QUECTEL_BC95_CTS);
100+
tr_debug("QUECTEL_BC95 flow control: RTS %d CTS %d", MBED_CONF_QUECTEL_BC95_RTS, MBED_CONF_QUECTEL_BC95_CTS);
101101
serial.set_flow_control(SerialBase::RTSCTS, MBED_CONF_QUECTEL_BC95_RTS, MBED_CONF_QUECTEL_BC95_CTS);
102102
#endif
103103
static QUECTEL_BC95 device(&serial);

features/cellular/framework/targets/QUECTEL/BG96/QUECTEL_BG96.cpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ CellularDevice *CellularDevice::get_default_instance()
7474
{
7575
static UARTSerial serial(MBED_CONF_QUECTEL_BG96_TX, MBED_CONF_QUECTEL_BG96_RX, MBED_CONF_QUECTEL_BG96_BAUDRATE);
7676
#if defined (MBED_CONF_UBLOX_AT_RTS) && defined(MBED_CONF_UBLOX_AT_CTS)
77-
tr_info("QUECTEL_BG96 flow control: RTS %d CTS %d", MBED_CONF_QUECTEL_BG96_RTS, MBED_CONF_QUECTEL_BG96_CTS);
77+
tr_debug("QUECTEL_BG96 flow control: RTS %d CTS %d", MBED_CONF_QUECTEL_BG96_RTS, MBED_CONF_QUECTEL_BG96_CTS);
7878
serial.set_flow_control(SerialBase::RTSCTS, MBED_CONF_QUECTEL_BG96_RTS, MBED_CONF_QUECTEL_BG96_CTS);
7979
#endif
8080
static QUECTEL_BG96 device(&serial);

features/cellular/framework/targets/QUECTEL/UG96/QUECTEL_UG96.cpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ CellularDevice *CellularDevice::get_default_instance()
5555
{
5656
static UARTSerial serial(MBED_CONF_QUECTEL_UG96_TX, MBED_CONF_QUECTEL_UG96_RX, MBED_CONF_QUECTEL_UG96_BAUDRATE);
5757
#if defined (MBED_CONF_QUECTEL_UG96_RTS) && defined (MBED_CONF_QUECTEL_UG96_CTS)
58-
tr_info("QUECTEL_UG96 flow control: RTS %d CTS %d", MBED_CONF_QUECTEL_UG96_RTS, MBED_CONF_QUECTEL_UG96_CTS);
58+
tr_debug("QUECTEL_UG96 flow control: RTS %d CTS %d", MBED_CONF_QUECTEL_UG96_RTS, MBED_CONF_QUECTEL_UG96_CTS);
5959
serial.set_flow_control(SerialBase::RTSCTS, MBED_CONF_QUECTEL_UG96_RTS, MBED_CONF_QUECTEL_UG96_CTS);
6060
#endif
6161
static QUECTEL_UG96 device(&serial);

features/cellular/framework/targets/TELIT/HE910/TELIT_HE910.cpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ CellularDevice *CellularDevice::get_default_instance()
6262
{
6363
static UARTSerial serial(MBED_CONF_TELIT_HE910_TX, MBED_CONF_TELIT_HE910_RX, MBED_CONF_TELIT_HE910_BAUDRATE);
6464
#if defined (MBED_CONF_TELIT_HE910_RTS) && defined (MBED_CONF_TELIT_HE910_CTS)
65-
tr_info("TELIT_HE910 flow control: RTS %d CTS %d", MBED_CONF_TELIT_HE910_RTS, MBED_CONF_TELIT_HE910_CTS);
65+
tr_debug("TELIT_HE910 flow control: RTS %d CTS %d", MBED_CONF_TELIT_HE910_RTS, MBED_CONF_TELIT_HE910_CTS);
6666
serial.set_flow_control(SerialBase::RTSCTS, MBED_CONF_TELIT_HE910_RTS, MBED_CONF_TELIT_HE910_CTS);
6767
#endif
6868
static TELIT_HE910 device(&serial);

features/cellular/framework/targets/UBLOX/AT/UBLOX_AT.cpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ CellularDevice *CellularDevice::get_default_instance()
6969
{
7070
static UARTSerial serial(MBED_CONF_UBLOX_AT_TX, MBED_CONF_UBLOX_AT_RX, MBED_CONF_UBLOX_AT_BAUDRATE);
7171
#if defined (MBED_CONF_UBLOX_AT_RTS) && defined(MBED_CONF_UBLOX_AT_CTS)
72-
tr_info("UBLOX_AT flow control: RTS %d CTS %d", MBED_CONF_UBLOX_AT_RTS, MBED_CONF_UBLOX_AT_CTS);
72+
tr_debug("UBLOX_AT flow control: RTS %d CTS %d", MBED_CONF_UBLOX_AT_RTS, MBED_CONF_UBLOX_AT_CTS);
7373
serial.set_flow_control(SerialBase::RTSCTS, MBED_CONF_UBLOX_AT_RTS, MBED_CONF_UBLOX_AT_CTS);
7474
#endif
7575
static UBLOX_AT device(&serial);

features/cellular/framework/targets/UBLOX/PPP/UBLOX_PPP.cpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ CellularDevice *CellularDevice::get_default_instance()
6363
{
6464
static UARTSerial serial(MBED_CONF_UBLOX_PPP_TX, MBED_CONF_UBLOX_PPP_RX, MBED_CONF_UBLOX_PPP_BAUDRATE);
6565
#if defined (MBED_CONF_UBLOX_AT_RTS) && defined(MBED_CONF_UBLOX_AT_CTS)
66-
tr_info("UBLOX_PPP flow control: RTS %d CTS %d", MBED_CONF_UBLOX_PPP_RTS, MBED_CONF_UBLOX_PPP_CTS);
66+
tr_debug("UBLOX_PPP flow control: RTS %d CTS %d", MBED_CONF_UBLOX_PPP_RTS, MBED_CONF_UBLOX_PPP_CTS);
6767
serial.set_flow_control(SerialBase::RTSCTS, MBED_CONF_UBLOX_PPP_RTS, MBED_CONF_UBLOX_PPP_CTS);
6868
#endif
6969
static UBLOX_PPP device(&serial);

targets/TARGET_NXP/TARGET_LPC176X/TARGET_UBLOX_C027/ONBOARD_UBLOX_PPP.cpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ CellularDevice *CellularDevice::get_target_default_instance()
5454
static UARTSerial serial(MDMTXD, MDMRXD, 115200);
5555
#if DEVICE_SERIAL_FC
5656
if (MDMRTS != NC && MDMCTS != NC) {
57-
tr_info("Modem flow control: RTS %d CTS %d", MDMRTS, MDMCTS);
57+
tr_debug("Modem flow control: RTS %d CTS %d", MDMRTS, MDMCTS);
5858
serial.set_flow_control(SerialBase::RTSCTS, MDMRTS, MDMCTS);
5959
}
6060
#endif

targets/TARGET_STM/TARGET_STM32F4/TARGET_MTS_DRAGONFLY_F411RE/ONBOARD_TELIT_HE910.cpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ CellularDevice *CellularDevice::get_target_default_instance()
5454
static UARTSerial serial(MDMTXD, MDMRXD, 115200);
5555
#if DEVICE_SERIAL_FC
5656
if (MDMRTS != NC && MDMCTS != NC) {
57-
tr_info("Modem flow control: RTS %d CTS %d", MDMRTS, MDMCTS);
57+
tr_debug("Modem flow control: RTS %d CTS %d", MDMRTS, MDMCTS);
5858
serial.set_flow_control(SerialBase::RTSCTS, MDMRTS, MDMCTS);
5959
}
6060
#endif

targets/TARGET_STM/TARGET_STM32F4/TARGET_STM32F439xI/TARGET_WIO_3G/ONBOARD_QUECTEL_BG96.cpp

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -25,10 +25,6 @@ ONBOARD_QUECTEL_BG96::ONBOARD_QUECTEL_BG96(FileHandle *fh) : QUECTEL_BG96(fh)
2525
{
2626
}
2727

28-
ONBOARD_QUECTEL_BG96::~ONBOARD_QUECTEL_BG96()
29-
{
30-
}
31-
3228
nsapi_error_t ONBOARD_QUECTEL_BG96::hard_power_on()
3329
{
3430
::onboard_modem_init();

targets/TARGET_STM/TARGET_STM32F4/TARGET_STM32F439xI/TARGET_WIO_3G/ONBOARD_QUECTEL_BG96.h

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,6 @@ namespace mbed {
2424
class ONBOARD_QUECTEL_BG96 : public QUECTEL_BG96 {
2525
public:
2626
ONBOARD_QUECTEL_BG96(FileHandle *fh);
27-
virtual ~ONBOARD_QUECTEL_BG96();
2827

2928
virtual nsapi_error_t hard_power_on();
3029
virtual nsapi_error_t hard_power_off();

targets/TARGET_STM/TARGET_STM32L4/TARGET_MTS_DRAGONFLY_L471QG/ONBOARD_SARA4_PPP.cpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ CellularDevice *CellularDevice::get_target_default_instance()
5454
static UARTSerial serial(MDMTXD, MDMRXD, 115200);
5555
#if DEVICE_SERIAL_FC
5656
if (MDMRTS != NC && MDMCTS != NC) {
57-
tr_info("Modem flow control: RTS %d CTS %d", MDMRTS, MDMCTS);
57+
tr_debug("Modem flow control: RTS %d CTS %d", MDMRTS, MDMCTS);
5858
serial.set_flow_control(SerialBase::RTSCTS, MDMRTS, MDMCTS);
5959
}
6060
#endif

targets/TARGET_STM/TARGET_STM32L4/TARGET_STM32L486xG/TARGET_MTB_ADV_WISE_1570/ONBOARD_QUECTEL_BC95.cpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ CellularDevice *CellularDevice::get_target_default_instance()
5555
static UARTSerial serial(MDMTXD, MDMRXD, 9600);
5656
#if DEVICE_SERIAL_FC
5757
if (MDMRTS != NC && MDMCTS != NC) {
58-
tr_info("Modem flow control: RTS %d CTS %d", MDMRTS, MDMCTS);
58+
tr_debug("Modem flow control: RTS %d CTS %d", MDMRTS, MDMCTS);
5959
serial.set_flow_control(SerialBase::RTSCTS, MDMRTS, MDMCTS);
6060
}
6161
#endif

0 commit comments

Comments
 (0)