net_polling_api.h

00001 /*
00002  * Copyright (c) 2013-2017, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 /**
00019  * \file net_polling_api.h
00020  * \brief ZigBeeIP Sleepy Host Data Poll API.
00021  *
00022  *  - arm_nwk_host_mode_set(), Set sleepy host new state.
00023  *  - arm_nwk_host_mode_get(), Read current host state.
00024  *  - net_host_enter_sleep_state_set(), Enable deep sleep state.
00025  *
00026  * The sleepy host default state is NET_HOST_FAST_POLL_MODE after bootstrap.
00027  * The stack always disables radio automatically between data polls.
00028  * The stack can also enable deep sleep when application net_host_enter_sleep_state_set().
00029  *
00030  * A sleepy host can change the host state to normal, which saves time and resources when the client is waiting for a large amount of data.
00031  *  - nwk_host_mode_set(NET_HOST_RX_ON_IDLE,0) A function call to trigger MLE handshake update automatically.
00032  * From NET_HOST_RX_ON_IDLE state back to polling state causes an MLE handshake with parent:
00033  *  - nwk_host_mode_set (NET_HOST_FAST_POLL_MODE,0), Enter fast mode.
00034  *  - nwk_host_mode_set (NET_HOST_SLOW_POLL_MODE,10), Enter slow poll mode by 10 seconds max data poll period.
00035  *
00036  * The stack will tell max sleepy time to the application by selecting min values from the following cases:
00037  *  - Next active system timer trigger
00038  *  - ND protocol next state trigger
00039  *  - MLE handshake trigger
00040  *  - PANA key pull trigger
00041  *  - Next data poll period
00042  *
00043  */
00044 
00045 #ifndef NET_POLLING_H_
00046 #define NET_POLLING_H_
00047 
00048 #include "ns_types.h"
00049 
00050 #ifdef __cplusplus
00051 extern "C" {
00052 #endif
00053 
00054 /*!
00055  * \enum net_host_mode_t
00056  * \brief Sleepy host states.
00057  */
00058 typedef enum net_host_mode  {
00059     NET_HOST_FAST_POLL_MODE,    /**< Sleepy host fast poll state, max poll period 400ms. */
00060     NET_HOST_SLOW_POLL_MODE,    /**< Sleepy host slow poll state, user-defined max period in seconds. */
00061     NET_HOST_RX_ON_IDLE,        /**< Disable polling and enable direct data flow from parent to host. */
00062     NET_HOST_MODE_NOT_ACTIVE,   /**< Host mode is not active. */
00063 } net_host_mode_t;
00064 
00065 /**
00066   * \brief Set new host state.
00067   *
00068   * \param interface_id Network interface ID.
00069   * \param mode New host state.
00070   * \param poll_time Poll time in seconds, only handled when NET_HOST_SLOW_POLL_MODE is enabled.
00071   *
00072   * Valid poll time for NET_HOST_SLOW_POLL_MODE is 0 < poll_time poll_time < 864001 (1 Day)
00073   *
00074   * \return 0, State update OK.
00075   * \return -1, Unknown state.
00076   * \return -2, Invalid time.
00077   * \return -3 MLE handshake trigger failure.
00078   *
00079   */
00080 
00081 extern int8_t arm_nwk_host_mode_set(int8_t interface_id, net_host_mode_t mode, uint32_t poll_time);
00082 /**
00083   * \brief Read current host state.
00084   *
00085   * \param interface_id Network interface ID.
00086   * \param mode A pointer to the location for saving the host state.
00087 
00088   * \return 0, State read update OK.
00089   * \return -1, The host role is router or the stack is idle.
00090   *
00091   */
00092 extern int8_t arm_nwk_host_mode_get(int8_t interface_id, net_host_mode_t *mode);
00093 
00094 /**
00095   * \brief Host sleep state control.
00096   *
00097   * \param interface_id Network interface ID.
00098   * \param state >0 enables power saving between data polling. Otherwise, only radio is disabled.
00099   *
00100   * When the application wants to save more power it can call net_host_enter_sleep_state_set(nwk_interface_id, 1).
00101   * When the application wants to disable sleep it just calls net_host_enter_sleep_state_set(nwk_interface_id, 0).
00102   */
00103 extern void arm_net_host_enter_sleep_state_set(int8_t interface_id, uint8_t state);
00104 
00105 #ifdef __cplusplus
00106 }
00107 #endif
00108 
00109 #endif /* NET_POLLING_H_ */