WisunInterface.h

00001 /*
00002  * Copyright (c) 2018-2019 ARM Limited. All rights reserved.
00003  * SPDX-License-Identifier: Apache-2.0
00004  * Licensed under the Apache License, Version 2.0 (the License); you may
00005  * not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  * http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an AS IS BASIS, WITHOUT
00012  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef WISUNINTERFACE_H
00018 #define WISUNINTERFACE_H
00019 
00020 #include "MeshInterfaceNanostack.h"
00021 
00022 /** Wi-SUN mesh network interface class
00023  *
00024  * Configure Nanostack to use Wi-SUN protocol.
00025  */
00026 class WisunInterface : public MeshInterfaceNanostack {
00027 public:
00028 
00029     /** Create an uninitialized WisunInterface
00030      *
00031      *  Must initialize to initialize the mesh on a phy.
00032      */
00033     WisunInterface() { }
00034 
00035     /** Create an initialized WisunInterface
00036      *
00037      */
00038     WisunInterface(NanostackRfPhy *phy) : MeshInterfaceNanostack(phy) { }
00039 
00040     /**
00041      * \brief Set Wi-SUN network name.
00042      *
00043      * Function stores new network name to mbed-mesh-api and uses it when connect() is called next time.
00044      * If device is already connected to the Wi-SUN network then device will restart network discovery after
00045      * changing the network name.
00046      *
00047      * Function overwrites network name defined by Mbed OS configuration.
00048      *
00049      * \param network_name Network name as NUL terminated string. Can't exceed 32 characters and can't be NULL.
00050      * \return MESH_ERROR_NONE on success.
00051      * \return MESH_ERROR_UNKNOWN in case of failure.
00052      * */
00053     mesh_error_t set_network_name(char *network_name);
00054 
00055     /**
00056      * \brief Set Wi-SUN network regulatory domain, operating class and operating mode.
00057      *
00058      * Function stores new parameters to mbed-mesh-api and uses them when connect() is called next time.
00059      * If device is already connected to the Wi-SUN network then device will restart network discovery after
00060      * changing the regulatory_domain, operating_class or operating_mode.
00061      *
00062      * Function overwrites parameters defined by Mbed OS configuration.
00063      *
00064      * \param regulatory_domain Values defined in Wi-SUN PHY-specification. Use 0xff to use leave parameter unchanged.
00065      * \param operating_class Values defined in Wi-SUN PHY-specification.  Use 0xff to use leave parameter unchanged.
00066      * \param operating_mode Values defined in Wi-SUN PHY-specification. Use 0xff to use leave parameter unchanged.
00067      * \return MESH_ERROR_NONE on success.
00068      * \return MESH_ERROR_UNKNOWN in case of failure.
00069      * */
00070     mesh_error_t set_network_regulatory_domain(uint8_t regulatory_domain = 0xff, uint8_t operating_class = 0xff, uint8_t operating_mode = 0xff);
00071 
00072     /**
00073      * \brief Set own certificate and private key reference to the Wi-SUN network.
00074      *
00075      * Function can be called several times if intermediate certificates are used. Then each call to the function
00076      * adds a certificate reference to own certificate chain. Certificates are in bottom up order i.e. the top certificate is given last.
00077      *
00078      * Function must be called before connecting the device i.e before call to connect() method.
00079      * Function will not copy certificate or key, therefore addresses must remain valid.
00080      *
00081      * \param cert Certificate address.
00082      * \param cert_len Certificate length in bytes.
00083      * \param cert_key Certificate key address.
00084      * \param cert_key_len Certificate key length in bytes.
00085      * \return MESH_ERROR_NONE on success.
00086      * \return MESH_ERROR_STATE if method is called after calling connect().
00087      * \return MESH_ERROR_MEMORY in case of memory allocation failure.
00088      * */
00089     mesh_error_t set_own_certificate(uint8_t *cert, uint16_t cert_len, uint8_t *cert_key = NULL, uint16_t cert_key_len = 0);
00090 
00091     /**
00092      * \brief Remove own certificates from the Wi-SUN network.
00093      *
00094      * Function must be called before connecting the device i.e before call to connect() method.
00095      *
00096      * \return MESH_ERROR_NONE on success.
00097      * \return MESH_ERROR_STATE if method is called after calling connect().
00098      * */
00099     mesh_error_t remove_own_certificates(void);
00100 
00101     /**
00102      * \brief Set trusted certificate reference to the Wi-SUN network.
00103      *
00104      * Function can be called several times. Certificates are in bottom up order i.e. the top certificate is given last.
00105      *
00106      * Function must be called before connecting the device i.e before call to connect() method.
00107      * Function will not copy certificate, therefore addresses must remain valid.
00108      *
00109      * \param cert Certificate address.
00110      * \param cert_len Certificate length in bytes.
00111      * \return MESH_ERROR_NONE on success.
00112      * \return MESH_ERROR_STATE if method is called after calling connect().
00113      * \return MESH_ERROR_MEMORY in case of memory allocation failure.
00114      * */
00115     mesh_error_t set_trusted_certificate(uint8_t *cert, uint16_t cert_len);
00116 
00117     /**
00118      * \brief Remove trusted certificates from the Wi-SUN network.
00119      *
00120      * Function must be called before connecting the device i.e before call to connect() method.
00121      *
00122      * \return MESH_ERROR_NONE on success.
00123      * \return MESH_ERROR_STATE if method is called after calling connect().
00124      * */
00125     mesh_error_t remove_trusted_certificates(void);
00126 
00127     /**
00128      * \brief Get router IP address
00129      *
00130      * \param address
00131      * \param len
00132      * */
00133     bool getRouterIpAddress(char *address, int8_t len);
00134 protected:
00135     Nanostack::WisunInterface *get_interface() const;
00136     virtual nsapi_error_t do_initialize();
00137 };
00138 
00139 #endif