Introducing hal/modem_api.h

Hasnain Virk · Hasnain Virk · commit ccbf00571fb3 · 2017-05-31T15:02:11.000+03:00
This provides a HAL layer for Modem bearing devices.
Provides a standard interface to upper layer drivers.
Platform providers will be implementing this API under their
specific targets.

As a reference, two implementations are provided under TARGET_C027 (UBLOX)
and TARGET_MTS_DRAGONFLY_F411RE (MultiTech).

targets.json now contains a tag "MODEM" which tells that this target
has a modem and the modem_api is protected by a flag DEVICE_MODEM
(following the DEVICE_SERIAL fashion ).
diff --git a/hal/modem_api.h b/hal/modem_api.h
@@ -0,0 +1,88 @@
+/* mbed Microcontroller Library
+ * Copyright (c) 2017 ARM Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+#ifndef MODEM_API_H_
+#define MODEM_API_H_
+
+/** modem_api is a standardizing API for Modem type devices under mbed-os.
+ * It provides a simple hardware abstraction layer on top of the modem drivers
+ * written for mbed-os.
+ *
+ * It is required from the engineers porting any modem type device (e.g., Cellular or Wifi)
+ * to provide an implementation of this API in their respective target folder as well as
+ * usage of standard PinNames (in PinNames.h) is highly encouraged. For example,
+ *
+ *   MDMTXD = P0_15, // Transmit Data
+ *   MDMRXD = P0_16, // Receive Data
+ *   MDMCTS = P0_17, // Clear to Send
+ *   MDMDCD = P0_18, // Data Carrier Detect
+ *   MDMDSR = P0_19, // Data Set Ready
+ *   MDMDTR = P0_20, // Data Terminal Ready (set high or use handshake)
+ *   MDMRI  = P0_21, // Ring Indicator
+ *   MDMRTS = P0_22, // Request to Send (set high or use handshake)
+ *
+ */
+
+#ifdef DEVICE_MODEM
+
+typedef enum {
+    POWER_READY=1,
+    POWERED_ON,
+    POWERED_OFF,
+    LOWEST_POWER_STATE
+} modem_state;
+
+/**
+ * modem_s is defined in objects.h inside the TARGET folder
+ */
+typedef struct modem_s modem_t;
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** Sets the modem up for powering on
+ *  modem_init() will be equivalent to plugging in the device, i.e.,
+ *  attaching power and serial port.
+ */
+void modem_init(modem_t *obj);
+
+/** Sets the modem in unplugged state
+ *  modem_deinit() will be equivalent to pulling the plug off of the device, i.e.,
+ *  detaching power and serial port.
+ *  This puts the modem in lowest power state.
+ */
+void modem_deinit(modem_t *obj);
+
+/** Powers up the modem
+ *  modem_power_up() will be equivalent to pressing the soft power button.
+ *  The driver may repeat this if the modem is not responsive to AT commands.
+
+ */
+void modem_power_up(modem_t *obj);
+
+/** Powers down the modem
+ *  modem_power_down() will be equivalent to turning off the modem by button press.
+ */
+void modem_power_down(modem_t *obj);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* DEVICE_MODEM*/
+#endif /* MODEM_API_H_ */
diff --git a/targets/TARGET_NXP/TARGET_LPC176X/TARGET_UBLOX_C027/mbed_modem_api.c b/targets/TARGET_NXP/TARGET_LPC176X/TARGET_UBLOX_C027/mbed_modem_api.c
@@ -0,0 +1,61 @@
+/* mbed Microcontroller Library
+ * Copyright (c) 2017 ARM Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "modem_api.h"
+#include "ublox_low_level_api.h"
+#include "gpio_api.h"
+#include "platform/mbed_wait_api.h"
+#include "PinNames.h"
+
+#if DEVICE_MODEM
+static void press_power_button(int time_ms)
+{
+    gpio_t gpio;
+
+    gpio_init_out_ex(&gpio, MDMPWRON, 0);
+    wait_ms(time_ms);
+    gpio_write(&gpio, 1);
+}
+
+void modem_init(modem_t *obj)
+{
+    //currently USB is not supported, so pass 0 to disable USB
+    //This call does everything except actually pressing the power button
+    ublox_mdm_powerOn(0);
+    obj->state = POWER_READY;
+}
+
+void modem_deinit(modem_t *obj)
+{
+    ublox_mdm_powerOff();
+    obj->state = LOWEST_POWER_STATE;
+}
+void modem_power_up(modem_t *obj)
+{
+    /* keep the power line low for 150 milisecond */
+    press_power_button(150);
+    /* give modem a little time to respond */
+    wait_ms(100);
+    obj->state = POWERED_ON;
+}
+
+void modem_power_down(modem_t *obj)
+{
+    /* keep the power line low for 1 second */
+    press_power_button(1000);
+    obj->state = POWERED_OFF;
+}
+#endif //DEVICE_MODEM
diff --git a/targets/TARGET_NXP/TARGET_LPC176X/objects.h b/targets/TARGET_NXP/TARGET_LPC176X/objects.h
@@ -71,6 +71,10 @@ struct spi_s {
     LPC_SSP_TypeDef *spi;
 };
 
+struct modem_s {
+    uint32_t state;
+};
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/targets/TARGET_STM/TARGET_STM32F4/TARGET_MTS_DRAGONFLY_F411RE/mbed_modem_api.c b/targets/TARGET_STM/TARGET_STM32F4/TARGET_MTS_DRAGONFLY_F411RE/mbed_modem_api.c
@@ -0,0 +1,64 @@
+/* mbed Microcontroller Library
+ * Copyright (c) 2017 ARM Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+#include "modem_api.h"
+#include "gpio_api.h"
+#include "platform/mbed_wait_api.h"
+#include "PinNames.h"
+
+#if DEVICE_MODEM
+static void press_power_button(int time_ms)
+{
+    gpio_t gpio;
+
+    gpio_init_out_ex(&gpio, MDMPWRON, 1);
+    gpio_write(&gpio, 0);
+    wait_ms(time_ms);
+    gpio_write(&gpio, 1);
+}
+
+void modem_init(modem_t *obj)
+{
+   //does nothing at the moment, TODO: MultiTech to add hardware initialization stuff if needed
+    obj->state = POWER_READY;
+}
+
+void modem_deinit(modem_t *obj)
+{
+    //does nothing at the moment, TODO: MultiTech to add hardware de-initialization stuff if needed
+    obj->state = LOWEST_POWER_STATE;
+}
+void modem_power_up(modem_t *obj)
+{
+    /* keep the power line low for 200 milisecond */
+    press_power_button(200);
+    /* give modem a little time to respond */
+    wait_ms(100);
+    obj->state = POWERED_ON;
+}
+
+void modem_power_down(modem_t *obj)
+{
+    gpio_t gpio;
+
+    gpio_init_out_ex(&gpio, MDMPWRON, 0);
+    /* keep the power line low for more than 10 seconds.
+     * If 3G_ON_OFF pin is kept low for more than a second, a controlled disconnect and shutdown takes
+     * place, Due to the network disconnect, shut-off can take up to 30 seconds. However, we wait for 10
+     * seconds only   */
+    wait_ms(10*1000);
+    obj->state = POWERED_OFF;
+}
+#endif //DEVICE_MODEM
diff --git a/targets/TARGET_STM/TARGET_STM32F4/TARGET_MTS_DRAGONFLY_F411RE/objects.h b/targets/TARGET_STM/TARGET_STM32F4/TARGET_MTS_DRAGONFLY_F411RE/objects.h
@@ -60,6 +60,10 @@ struct analogin_s {
     uint8_t channel;
 };
 
+struct modem_s {
+    uint32_t state;
+};
+
 #include "common_objects.h"
 
 #ifdef __cplusplus
diff --git a/targets/targets.json b/targets/targets.json
@@ -251,7 +251,7 @@
         "extra_labels": ["NXP", "LPC176X", "FLASH_CMSIS_ALGO", "UBLOX_MODEM"],
         "macros": ["TARGET_LPC1768"],
         "inherits": ["LPCTarget"],
-        "device_has": ["ANALOGIN", "ANALOGOUT", "CAN", "DEBUG_AWARENESS", "ERROR_RED", "ETHERNET", "I2C", "I2CSLAVE", "INTERRUPTIN", "PORTIN", "PORTINOUT", "PORTOUT", "PWMOUT", "RTC", "SERIAL", "SERIAL_FC", "SLEEP", "SPI", "SPISLAVE", "STDIO_MESSAGES", "FLASH"],
+        "device_has": ["ANALOGIN", "ANALOGOUT", "CAN", "DEBUG_AWARENESS", "ERROR_RED", "ETHERNET", "I2C", "I2CSLAVE", "INTERRUPTIN", "PORTIN", "PORTINOUT", "PORTOUT", "PWMOUT", "RTC", "SERIAL", "SERIAL_FC", "SLEEP", "SPI", "SPISLAVE", "STDIO_MESSAGES", "FLASH", "MODEM"],
         "release_versions": ["2", "5"],
         "features": ["LWIP"],
         "device_name": "LPC1768"
@@ -1343,7 +1343,7 @@
             "function": "MTSCode.combine_bins_mts_dragonfly",
             "toolchains": ["GCC_ARM", "ARM_STD", "ARM_MICRO"]
         },
-        "device_has": ["ANALOGIN", "I2C", "I2CSLAVE", "INTERRUPTIN", "PORTIN", "PORTINOUT", "PORTOUT", "PWMOUT", "RTC", "SERIAL", "SLEEP", "SPI", "SPISLAVE", "SPI_ASYNCH", "STDIO_MESSAGES"],
+        "device_has": ["ANALOGIN", "I2C", "I2CSLAVE", "INTERRUPTIN", "PORTIN", "PORTINOUT", "PORTOUT", "PWMOUT", "RTC", "SERIAL", "SLEEP", "SPI", "SPISLAVE", "SPI_ASYNCH", "STDIO_MESSAGES", "MODEM"],
         "release_versions": ["2", "5"],
         "device_name": "STM32F411RE"
     },
