src/app/clusters/ias-zone-server/ias-zone-server.h

   1 /**
   2  *
   3  *    Copyright (c) 2020 Project CHIP Authors
   4  *
   5  *    Licensed under the Apache License, Version 2.0 (the "License");
   6  *    you may not use this file except in compliance with the License.
   7  *    You may obtain a copy of the License at
   8  *
   9  *        http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  *    Unless required by applicable law or agreed to in writing, software
  12  *    distributed under the License is distributed on an "AS IS" BASIS,
  13  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  *    See the License for the specific language governing permissions and
  15  *    limitations under the License.
  16  */
  17
  18 /**
  19  *
  20  *    Copyright (c) 2020 Silicon Labs
  21  *
  22  *    Licensed under the Apache License, Version 2.0 (the "License");
  23  *    you may not use this file except in compliance with the License.
  24  *    You may obtain a copy of the License at
  25  *
  26  *        http://www.apache.org/licenses/LICENSE-2.0
  27  *
  28  *    Unless required by applicable law or agreed to in writing, software
  29  *    distributed under the License is distributed on an "AS IS" BASIS,
  30  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  31  *    See the License for the specific language governing permissions and
  32  *    limitations under the License.
  33  */
  34 /****************************************************************************
  35  * @file
  36  * @brief This is the source for the plugin used to
  37  *add an IAS Zone cluster server to a project. This
  38  *source handles zone enrollment and storing of
  39  * attributes from a CIE device and provides an API
  40  *for different plugins to post updated zone status
  41  *values.
  42  *******************************************************************************
  43  ******************************************************************************/
  44
  45 #pragma once
  46
  47 #include <app/util/af-types.h>
  48
  49 #define EM_AF_UNKNOWN_ENDPOINT 0
  50 // Absolute max backoff time, at least one retry a day
  51 // (ie. 24 hours * 60 minutes * 60 seconds).
  52 #define IAS_ZONE_STATUS_QUEUE_RETRY_ABS_MAX_BACKOFF_TIME_SEC (24 * 60 * 60)
  53
  54 // Definitions for the IAS Zone enrollment mode.
  55 typedef enum
  56 {
  57     EMBER_ZCL_IAS_ZONE_ENROLLMENT_MODE_TRIP_TO_PAIR             = 0x00,
  58     EMBER_ZCL_IAS_ZONE_ENROLLMENT_MODE_AUTO_ENROLLMENT_RESPONSE = 0x01,
  59     EMBER_ZCL_IAS_ZONE_ENROLLMENT_MODE_REQUEST                  = 0x02
  60 } EmberAfIasZoneEnrollmentMode;
  61
  62 // Status queue retry parameters
  63 typedef struct
  64 {
  65     uint8_t firstBackoffTimeSec;
  66     uint8_t backoffSeqCommonRatio;
  67     uint32_t maxBackoffTimeSec;
  68     bool unlimitedRetries;
  69     uint8_t maxRetryAttempts;
  70 } IasZoneStatusQueueRetryConfig;
  71
  72 /** @brief Updates the zone status for an endpoint.
  73  *
  74  * This function will update the zone status attribute of the specified endpoint
  75  * using the specified new zone status. It will then notify the CIE of the
  76  * updated status.
  77  *
  78  * @param endpoint The endpoint whose zone status attribute is to be updated.
  79  * @param newStatus The new status to write to the attribute.
  80  * @param timeSinceStatusOccurredQs The amount of time (in quarter seconds) that
  81  *   has passed since the status change occurred.
  82  *
  83  * @return EMBER_SUCCESS if the attribute update and notify succeeded, error
  84  * code otherwise.
  85  */
  86 EmberStatus emberAfPluginIasZoneServerUpdateZoneStatus(chip::EndpointId endpoint, uint16_t newStatus,
  87                                                        uint16_t timeSinceStatusOccurredQs);
  88
  89 /** @brief Gets the CIE assigned zone id of a given endpoint.
  90  *
  91  * This function will return the zone ID that was assigned to the given
  92  * endpoint by the CIE at time of enrollment.
  93  *
  94  * @param endpoint The endpoint whose ID is to be queried.
  95  *
  96  * @return The zone ID assigned by the CIE at time of enrollment.
  97  */
  98 uint8_t emberAfPluginIasZoneServerGetZoneId(chip::EndpointId endpoint);
  99
 100 /** @brief Determines the enrollment status of a given endpoint.
 101  *
 102  * This function will return true or false depending on whether the specified
 103  * endpoint has undergone IAS Zone Enrollment.
 104  *
 105  * @param endpoint The endpoint whose enrollment status is to be queried.
 106  *
 107  * @return True if enrolled, false otherwise.
 108  */
 109 bool emberAfIasZoneClusterAmIEnrolled(chip::EndpointId endpoint);
 110
 111 /** @brief Set the enrollment status.
 112  *
 113  * This function will return the status of the set enrollment method attempt.
 114  *
 115  * @param endpoint The endpoint whose enrollment method is to be set
 116  * @param method The enrollment method that should be set
 117  *
 118  * @return An ::EmberAfStatus value indicating the status of the set action.
 119  */
 120 EmberAfStatus emberAfPluginIasZoneClusterSetEnrollmentMethod(chip::EndpointId endpoint, EmberAfIasZoneEnrollmentMode method);
 121
 122 /** @brief Configure the retry parameters of the status queue.
 123  *
 124  * This function will configure the status queue retry parameters.
 125  *
 126  * @param retryConfig Status queue retry configuration.
 127  */
 128 EmberStatus emberAfIasZoneServerConfigStatusQueueRetryParams(IasZoneStatusQueueRetryConfig * retryConfig);
 129
 130 /** @brief Set the retry parameters of the status queue to default.
 131  *
 132  * This function will set the status queue retry parameters to their default values.
 133  */
 134 void emberAfIasZoneServerSetStatusQueueRetryParamsToDefault(void);
 135
 136 /** @brief Discards any pendint events in the status queue and sets it inactive.
 137  *
 138  * This function will discard any pending event pending in the status queue.
 139  * Also, the status queue event control manager will be inactivated.
 140  */
 141 void emberAfIasZoneServerDiscardPendingEventsInStatusQueue(void);
 142
 143 /** @brief Prints information on the satus queue.
 144  */
 145 void emberAfPluginIasZoneServerPrintQueue(void);
 146
 147 /** @brief Prints the satus queue config.
 148  */
 149 void emberAfPluginIasZoneServerPrintQueueConfig(void);