Kenji Arai / mbed-os_TYBLE16

mbed-os5 only for TYBLE16

Dependents:   TYBLE16_simple_data_logger TYBLE16_MP3_Air

features/netsocket/CellularInterface.h@0:5b88d5760320, 2019-12-17 (annotated)

Committer:
kenjiArai
Date:
Tue Dec 17 23:23:45 2019 +0000
Revision:
0:5b88d5760320
Child:
1:9db0e321a9f4
mbed-os5 only for TYBLE16

Who changed what in which revision?

UserRevisionLine numberNew contents of line
kenjiArai 0:5b88d5760320 1 /* Copyright (c) 2019 ARM Limited
kenjiArai 0:5b88d5760320 2 * SPDX-License-Identifier: Apache-2.0
kenjiArai 0:5b88d5760320 3 *
kenjiArai 0:5b88d5760320 4 * Licensed under the Apache License, Version 2.0 (the "License");
kenjiArai 0:5b88d5760320 5 * you may not use this file except in compliance with the License.
kenjiArai 0:5b88d5760320 6 * You may obtain a copy of the License at
kenjiArai 0:5b88d5760320 7 *
kenjiArai 0:5b88d5760320 8 * http://www.apache.org/licenses/LICENSE-2.0
kenjiArai 0:5b88d5760320 9 *
kenjiArai 0:5b88d5760320 10 * Unless required by applicable law or agreed to in writing, software
kenjiArai 0:5b88d5760320 11 * distributed under the License is distributed on an "AS IS" BASIS,
kenjiArai 0:5b88d5760320 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
kenjiArai 0:5b88d5760320 13 * See the License for the specific language governing permissions and
kenjiArai 0:5b88d5760320 14 * limitations under the License.
kenjiArai 0:5b88d5760320 15 */
kenjiArai 0:5b88d5760320 16
kenjiArai 0:5b88d5760320 17 #ifndef CELLULAR_INTERFACE_H_
kenjiArai 0:5b88d5760320 18 #define CELLULAR_INTERFACE_H_
kenjiArai 0:5b88d5760320 19
kenjiArai 0:5b88d5760320 20 #include "netsocket/NetworkInterface.h"
kenjiArai 0:5b88d5760320 21
kenjiArai 0:5b88d5760320 22 /**
kenjiArai 0:5b88d5760320 23 * @addtogroup cellular
kenjiArai 0:5b88d5760320 24 * @{
kenjiArai 0:5b88d5760320 25 */
kenjiArai 0:5b88d5760320 26
kenjiArai 0:5b88d5760320 27 /** Common interface that is shared between cellular interfaces.
kenjiArai 0:5b88d5760320 28 */
kenjiArai 0:5b88d5760320 29 class CellularInterface: public NetworkInterface {
kenjiArai 0:5b88d5760320 30
kenjiArai 0:5b88d5760320 31 public:
kenjiArai 0:5b88d5760320 32 /** Get the default cellular interface.
kenjiArai 0:5b88d5760320 33 *
kenjiArai 0:5b88d5760320 34 * This is provided as a weak method so applications can override.
kenjiArai 0:5b88d5760320 35 * Default behavior is to get the target's default interface, if
kenjiArai 0:5b88d5760320 36 * any.
kenjiArai 0:5b88d5760320 37 *
kenjiArai 0:5b88d5760320 38 * @return pointer to interface, if any.
kenjiArai 0:5b88d5760320 39 */
kenjiArai 0:5b88d5760320 40 static CellularInterface *get_default_instance();
kenjiArai 0:5b88d5760320 41
kenjiArai 0:5b88d5760320 42 /** Set the cellular network credentials.
kenjiArai 0:5b88d5760320 43 *
kenjiArai 0:5b88d5760320 44 * Please check documentation of connect() for default behavior of APN settings.
kenjiArai 0:5b88d5760320 45 *
kenjiArai 0:5b88d5760320 46 * @param apn Access point name.
kenjiArai 0:5b88d5760320 47 * @param uname Username (optional).
kenjiArai 0:5b88d5760320 48 * @param pwd Password (optional).
kenjiArai 0:5b88d5760320 49 */
kenjiArai 0:5b88d5760320 50 virtual void set_credentials(const char *apn, const char *uname = 0,
kenjiArai 0:5b88d5760320 51 const char *pwd = 0) = 0;
kenjiArai 0:5b88d5760320 52
kenjiArai 0:5b88d5760320 53 /** Set the plmn. PLMN controls to what network device registers.
kenjiArai 0:5b88d5760320 54 *
kenjiArai 0:5b88d5760320 55 * @param plmn user to force what network to register.
kenjiArai 0:5b88d5760320 56 */
kenjiArai 0:5b88d5760320 57 virtual void set_plmn(const char *plmn) = 0;
kenjiArai 0:5b88d5760320 58
kenjiArai 0:5b88d5760320 59 /** Set the PIN code for SIM card.
kenjiArai 0:5b88d5760320 60 *
kenjiArai 0:5b88d5760320 61 * @param sim_pin PIN for the SIM card.
kenjiArai 0:5b88d5760320 62 */
kenjiArai 0:5b88d5760320 63 virtual void set_sim_pin(const char *sim_pin) = 0;
kenjiArai 0:5b88d5760320 64
kenjiArai 0:5b88d5760320 65 /** Attempt to connect to a cellular network with a PIN and credentials.
kenjiArai 0:5b88d5760320 66 *
kenjiArai 0:5b88d5760320 67 * @param sim_pin PIN for the SIM card.
kenjiArai 0:5b88d5760320 68 * @param apn Access point name (optional).
kenjiArai 0:5b88d5760320 69 * @param uname Username (optional).
kenjiArai 0:5b88d5760320 70 * @param pwd Password (optional).
kenjiArai 0:5b88d5760320 71 * @return NSAPI_ERROR_OK on success, or negative error code on failure.
kenjiArai 0:5b88d5760320 72 */
kenjiArai 0:5b88d5760320 73 virtual nsapi_error_t connect(const char *sim_pin, const char *apn = 0,
kenjiArai 0:5b88d5760320 74 const char *uname = 0,
kenjiArai 0:5b88d5760320 75 const char *pwd = 0) = 0;
kenjiArai 0:5b88d5760320 76
kenjiArai 0:5b88d5760320 77 /** Attempt to connect to a cellular network.
kenjiArai 0:5b88d5760320 78 *
kenjiArai 0:5b88d5760320 79 * If the SIM requires a PIN, and it is invalid or not set, NSAPI_ERROR_AUTH_ERROR is returned.
kenjiArai 0:5b88d5760320 80 *
kenjiArai 0:5b88d5760320 81 * @return NSAPI_ERROR_OK on success, or negative error code on failure.
kenjiArai 0:5b88d5760320 82 */
kenjiArai 0:5b88d5760320 83 virtual nsapi_error_t connect() = 0;
kenjiArai 0:5b88d5760320 84
kenjiArai 0:5b88d5760320 85 /** Stop the interface.
kenjiArai 0:5b88d5760320 86 *
kenjiArai 0:5b88d5760320 87 * @return NSAPI_ERROR_OK on success, or error code on failure.
kenjiArai 0:5b88d5760320 88 */
kenjiArai 0:5b88d5760320 89 virtual nsapi_error_t disconnect() = 0;
kenjiArai 0:5b88d5760320 90
kenjiArai 0:5b88d5760320 91 /** Check if the connection is currently established.
kenjiArai 0:5b88d5760320 92 *
kenjiArai 0:5b88d5760320 93 * @return `true` if the cellular module have successfully acquired a carrier and is
kenjiArai 0:5b88d5760320 94 * connected to an external packet data network using PPP, `false` otherwise.
kenjiArai 0:5b88d5760320 95 */
kenjiArai 0:5b88d5760320 96 virtual bool is_connected() = 0;
kenjiArai 0:5b88d5760320 97
kenjiArai 0:5b88d5760320 98 /** Get the local IP address.
kenjiArai 0:5b88d5760320 99 *
kenjiArai 0:5b88d5760320 100 * @return Null-terminated representation of the local IP address,
kenjiArai 0:5b88d5760320 101 * or null if no IP address has been received.
kenjiArai 0:5b88d5760320 102 */
kenjiArai 0:5b88d5760320 103 virtual const char *get_ip_address() = 0;
kenjiArai 0:5b88d5760320 104
kenjiArai 0:5b88d5760320 105 /** Get the local network mask.
kenjiArai 0:5b88d5760320 106 *
kenjiArai 0:5b88d5760320 107 * @return Null-terminated representation of the local network mask,
kenjiArai 0:5b88d5760320 108 * or null if no network mask has been received.
kenjiArai 0:5b88d5760320 109 */
kenjiArai 0:5b88d5760320 110 virtual const char *get_netmask() = 0;
kenjiArai 0:5b88d5760320 111
kenjiArai 0:5b88d5760320 112 /** Get the local gateways.
kenjiArai 0:5b88d5760320 113 *
kenjiArai 0:5b88d5760320 114 * @return Null-terminated representation of the local gateway,
kenjiArai 0:5b88d5760320 115 * or null if no network mask has been received.
kenjiArai 0:5b88d5760320 116 */
kenjiArai 0:5b88d5760320 117 virtual const char *get_gateway() = 0;
kenjiArai 0:5b88d5760320 118
kenjiArai 0:5b88d5760320 119 /** @copydoc NetworkInterface::cellularBase
kenjiArai 0:5b88d5760320 120 */
kenjiArai 0:5b88d5760320 121 MBED_DEPRECATED_SINCE("mbed-os-5.12", "Migrated to CellularInterface")
kenjiArai 0:5b88d5760320 122 virtual CellularInterface *cellularBase()
kenjiArai 0:5b88d5760320 123 {
kenjiArai 0:5b88d5760320 124 return this;
kenjiArai 0:5b88d5760320 125 }
kenjiArai 0:5b88d5760320 126
kenjiArai 0:5b88d5760320 127 /** @copydoc NetworkInterface::cellularInterface
kenjiArai 0:5b88d5760320 128 */
kenjiArai 0:5b88d5760320 129 virtual CellularInterface *cellularInterface()
kenjiArai 0:5b88d5760320 130 {
kenjiArai 0:5b88d5760320 131 return this;
kenjiArai 0:5b88d5760320 132 }
kenjiArai 0:5b88d5760320 133
kenjiArai 0:5b88d5760320 134 #if !defined(DOXYGEN_ONLY)
kenjiArai 0:5b88d5760320 135
kenjiArai 0:5b88d5760320 136 protected:
kenjiArai 0:5b88d5760320 137 /** Get the target's default cellular interface.
kenjiArai 0:5b88d5760320 138 *
kenjiArai 0:5b88d5760320 139 * This is provided as a weak method so targets can override. The
kenjiArai 0:5b88d5760320 140 * default implementation configures and returns the OnBoardModemInterface,
kenjiArai 0:5b88d5760320 141 * if available.
kenjiArai 0:5b88d5760320 142 *
kenjiArai 0:5b88d5760320 143 * @return Pointer to interface, if any.
kenjiArai 0:5b88d5760320 144 */
kenjiArai 0:5b88d5760320 145 static CellularInterface *get_target_default_instance();
kenjiArai 0:5b88d5760320 146
kenjiArai 0:5b88d5760320 147 #endif //!defined(DOXYGEN_ONLY)
kenjiArai 0:5b88d5760320 148
kenjiArai 0:5b88d5760320 149 public:
kenjiArai 0:5b88d5760320 150 /** Set default parameters on a cellular interface.
kenjiArai 0:5b88d5760320 151 *
kenjiArai 0:5b88d5760320 152 * A cellular interface instantiated directly or using
kenjiArai 0:5b88d5760320 153 * CellularInterface::get_default_instance() is initially unconfigured.
kenjiArai 0:5b88d5760320 154 * This call can be used to set the default parameters that would
kenjiArai 0:5b88d5760320 155 * have been set if the interface had been requested using
kenjiArai 0:5b88d5760320 156 * NetworkInterface::get_default_instance() (see nsapi JSON
kenjiArai 0:5b88d5760320 157 * configuration).
kenjiArai 0:5b88d5760320 158 */
kenjiArai 0:5b88d5760320 159 virtual void set_default_parameters();
kenjiArai 0:5b88d5760320 160 };
kenjiArai 0:5b88d5760320 161
kenjiArai 0:5b88d5760320 162 #endif // CELLULAR_INTERFACE_H_