From 01f1c4190c6a3075c04bce0ce555b29cb92e06bc Mon Sep 17 00:00:00 2001 From: Ari Parkkila Date: Wed, 9 Jan 2019 13:04:17 +0200 Subject: [PATCH] Cellular: Update cellular documentation --- features/cellular/README.md | 30 ++----------------- .../cellular/framework/API/CellularContext.h | 12 +++++++- .../cellular/framework/API/CellularDevice.h | 9 ++++++ .../framework/API/CellularInformation.h | 9 ++++++ .../cellular/framework/API/CellularNetwork.h | 29 ++++++++---------- features/cellular/framework/API/CellularSMS.h | 9 ++++++ features/cellular/framework/AT/ATHandler.h | 7 ++--- 7 files changed, 55 insertions(+), 50 deletions(-) diff --git a/features/cellular/README.md b/features/cellular/README.md index a69b2cfa12..c79c758de7 100644 --- a/features/cellular/README.md +++ b/features/cellular/README.md @@ -2,26 +2,21 @@ This is the Github repo for Mbed cellular connectivity: - easy_cellular/ - EasyCellularConnection Simplified cellular usage based on `CellularBase.h` - CellularConnectionUtil A utility class for cellular connection - framework/ API Application Programming Interface for cellular connectivity AT AT implementation based on 3GPP TS 27.007 specification common Common and utility sources + device Implementation of cellular device and state machine targets Vendor specific cellular module adaptations TESTS Cellular Greentea test - UNITTESTS Cellular unit test +**Application developers should only use API folder. ## Known limitations **Please note that this is a first release of Cellular framework and is subject to further development in future.** -Only UDP is supported when using AT commands to control sockets in an IP stack built into the cellular modem. If TCP is required, use the PPP/LWIP stack. - ## Supported modules You can find currently supported cellular modules in the `framework/targets/` folder, where we also add support for new cellular modules. @@ -30,23 +25,6 @@ You can find currently supported cellular modules in the `framework/targets/` fo You can change cellular defaults in the `mbed_lib.json` configuration file. -You can also override cellular defaults in the `mbed_app.json` configuration file: - - "config": { - "cellular_plmn": { - "help": "PLMN selection, 0=auto", - "value": 0 - }, - "apn": { - "help": "Access point name, e.g. internet", - "value": "\"internet\"" - }, - "cellular_sim_pin": { - "help": "PIN code", - "value": "\"1234\"" - } - } - ## Debug traces You can define the debug tracing level in the `mbed_app.json` configuration file: @@ -77,9 +55,7 @@ The `TESTS` folder contains Greentea tests for cellular specific classes. You ne ## Unit tests -The `UNITTESTS` folder contains unit tests for cellular specific classes. Unit tests are based on the stubbing method. - -You can run those tests locally by running `./run_tests` script under the `UNITTESTS/` folder. +Cellular unit tests are in Mbed OS root `UNITTESTS`. Unit tests are based on the stubbing method. You need the following applications: `cpputest`, `gcov` and `lcov` (genhtml) for running the tests. diff --git a/features/cellular/framework/API/CellularContext.h b/features/cellular/framework/API/CellularContext.h index 0e3cdaa4b5..44bd4ec581 100644 --- a/features/cellular/framework/API/CellularContext.h +++ b/features/cellular/framework/API/CellularContext.h @@ -22,6 +22,12 @@ namespace mbed { +/** + * @addtogroup cellular + * @{ + */ + +/// CellularContext is CellularBase/NetworkInterface with extensions for cellular connectivity class CellularContext : public CellularBase { public: @@ -50,7 +56,7 @@ public: Week }; - /* PDP Context information */ + /// PDP Context information struct pdpcontext_params_t { char apn[MAX_ACCESSPOINT_NAME_LENGTH + 1]; char local_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1]; @@ -255,6 +261,10 @@ protected: // Device specific implementations might need these so protected const char *_pwd; }; +/** + * @} + */ + } // namespace mbed diff --git a/features/cellular/framework/API/CellularDevice.h b/features/cellular/framework/API/CellularDevice.h index e42bad08e6..61a40a3e92 100644 --- a/features/cellular/framework/API/CellularDevice.h +++ b/features/cellular/framework/API/CellularDevice.h @@ -35,6 +35,11 @@ class FileHandle; const int MAX_PIN_SIZE = 8; const int MAX_PLMN_SIZE = 16; +/** + * @addtogroup cellular + * @{ + */ + /** * Class CellularDevice * @@ -279,6 +284,10 @@ private: Callback _status_cb; }; +/** + * @} + */ + } // namespace mbed #endif // CELLULAR_DEVICE_H_ diff --git a/features/cellular/framework/API/CellularInformation.h b/features/cellular/framework/API/CellularInformation.h index 63c02c0091..9ab79d6e92 100644 --- a/features/cellular/framework/API/CellularInformation.h +++ b/features/cellular/framework/API/CellularInformation.h @@ -23,6 +23,11 @@ namespace mbed { +/** + * @addtogroup cellular + * @{ + */ + /** * Class CellularInformation * @@ -83,6 +88,10 @@ public: virtual nsapi_error_t get_serial_number(char *buf, size_t buf_size, SerialNumberType type = SN) = 0; }; +/** + * @} + */ + } // namespace mbed #endif // CELLULAR_INFORMATION_H_ diff --git a/features/cellular/framework/API/CellularNetwork.h b/features/cellular/framework/API/CellularNetwork.h index ec6f3b74a1..7e91c1b384 100644 --- a/features/cellular/framework/API/CellularNetwork.h +++ b/features/cellular/framework/API/CellularNetwork.h @@ -1,11 +1,3 @@ -/* - * Copyright (c) 2017, Arm Limited and affiliates. - * SPDX-License-Identifier: Apache-2.0 - * - * 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 @@ -32,18 +24,16 @@ const int MAX_OPERATOR_NAME_LONG = 16; const int MAX_OPERATOR_NAME_SHORT = 8; /** - * Class CellularNetwork - * - * An abstract interface for connecting to a network and getting information from it. + * @addtogroup cellular + * @{ */ + +/// An abstract interface for connecting to a network and getting information from it. class CellularNetwork { protected: // friend of CellularDevice so that it's the only way to close/delete this class. friend class CellularDevice; - /** - * virtual Destructor - */ virtual ~CellularNetwork() {} public: @@ -112,7 +102,7 @@ public: RAT_MAX = 11 // to reserve string array }; - // 3GPP TS 27.007 - 7.3 PLMN selection +COPS + /// 3GPP TS 27.007 - 7.3 PLMN selection +COPS struct operator_t { enum Status { Unknown, @@ -141,6 +131,7 @@ public: typedef CellularList operList_t; + /// Cellular operator names in numeric and alpha format struct operator_names_t { char numeric[MAX_OPERATOR_NAME_SHORT + 1]; char alpha[MAX_OPERATOR_NAME_LONG + 1]; @@ -154,7 +145,7 @@ public: }; typedef CellularList operator_names_list; - /* Network registering mode */ + /// Network registering mode enum NWRegisteringMode { NWModeAutomatic = 0, // automatic registering NWModeManual, // manual registering with plmn @@ -163,7 +154,7 @@ public: NWModeManualAutomatic // if manual fails, fallback to automatic }; - /* Network registration information */ + /// Network registration information struct registration_params_t { RegistrationType _type; RegistrationStatus _status; @@ -365,6 +356,10 @@ public: virtual nsapi_error_t get_registration_params(RegistrationType type, registration_params_t ®_params) = 0; }; +/** + * @} + */ + } // namespace mbed #endif // CELLULAR_NETWORK_H_ diff --git a/features/cellular/framework/API/CellularSMS.h b/features/cellular/framework/API/CellularSMS.h index 3d91635b58..54d2afc2c4 100644 --- a/features/cellular/framework/API/CellularSMS.h +++ b/features/cellular/framework/API/CellularSMS.h @@ -35,6 +35,11 @@ const uint16_t SMS_SIM_WAIT_TIME_MILLISECONDS = 200; const int SMS_ERROR_MULTIPART_ALL_PARTS_NOT_READ = -5001; +/** + * @addtogroup cellular + * @{ + */ + /** * Class CellularSMS * @@ -162,6 +167,10 @@ public: virtual void set_extra_sim_wait_time(int sim_wait_time) = 0; }; +/** + * @} + */ + } // namespace mbed #endif // CELLULAR_SMS_H_ diff --git a/features/cellular/framework/AT/ATHandler.h b/features/cellular/framework/AT/ATHandler.h index 3d7a128ca5..9b26b8eb01 100644 --- a/features/cellular/framework/AT/ATHandler.h +++ b/features/cellular/framework/AT/ATHandler.h @@ -53,16 +53,13 @@ enum DeviceErrorType { DeviceErrorTypeErrorCME // AT ERROR CME }; -/* struct used when getting at response error. Defines error code and type */ +/** AT response error with error code and type */ struct device_err_t { DeviceErrorType errType; int errCode; }; -/** Class ATHandler - * - * Class for sending AT commands and parsing AT responses. - */ +/// Class for sending AT commands and parsing AT responses. class ATHandler { public: