fhss_channel.c

00001 /*
00002  * Copyright (c) 2016-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 #include "nsconfig.h"
00018 #include "ns_types.h"
00019 #include "fhss_api.h "
00020 #include "fhss_config.h "
00021 #include "fhss.h"
00022 #include "fhss_channel.h"
00023 #include "fhss_beacon.h"
00024 #include "channel_list.h"
00025 #include "randLIB.h"
00026 #include "ns_trace.h"
00027 
00028 #define TRACE_GROUP "fhss"
00029 
00030 // Enable this flag to use channel traces
00031 //#define FHSS_CHANNEL_DEBUG
00032 
00033 static uint8_t fhss_get_bc_index(const fhss_structure_t *fhss_structure);
00034 
00035 uint8_t fhss_calc_channel_shuffle(uint8_t index, uint16_t number_of_channels, uint8_t number_of_broadcast_channels)
00036 {
00037     /* To break the ...1, 2, 3, 4,... hopping sequence and to spread broadcast channels equally on frequency band.
00038      *
00039      * Also to randomise the sequence, for Unicast channels:
00040      * - Even indexes are divided by 2
00041      * - Odd indexes are divided by 2 and result is subtracted from highest Unicast index (which is (number_of_channels-number_of_broadcast_channels) - 1)
00042      *
00043      *
00044      * Example:
00045      * Hopping sequence:      Without Unicast randomising:      With Unicast randomising:
00046      *  0,  1,  2,  3,        0,  4,  8, 12,                    0, 14,  4, 10,
00047      *  4,  5,  6,  7,        1,  5,  9, 13,                    8,  6, 12,  2,
00048      *  8,  9, 10, 11,        2,  6, 10, 14,                    1, 13,  5,  9,
00049      * 12, 13, 14, 15         3,  7, 11, 15,                    3,  7, 11, 15,
00050      *
00051      * If number of broadcast channels is 4 (last 4 indexes 3, 7, 11, 15), the hopping sequence is: 3, 0, 14, 4, 7, 10, 8, 6, 11, 12, 2, 1, 15, 13, 5, 9
00052      */
00053 #ifndef DISABLE_CHANNEL_SHUFFLE
00054     // Unicast randomising
00055     if (index < (number_of_channels-number_of_broadcast_channels)) {
00056         if (!(index % 2)) {
00057             index /= 2;
00058         } else {
00059             index = ((number_of_channels-number_of_broadcast_channels) - 1) - (index / 2);
00060         }
00061     }
00062     // Spread Broadcast channels
00063     index = (index % number_of_broadcast_channels) * (number_of_channels / number_of_broadcast_channels) + (index/number_of_broadcast_channels);
00064 #endif /*DISABLE_CHANNEL_SHUFFLE*/
00065     return index;
00066 }
00067 
00068 uint8_t fhss_add_channel_list_counter(uint8_t index, uint16_t number_of_channels, uint16_t channel_list_counter, uint8_t *scramble_table)
00069 {
00070     /* To avoid repeating same channel list constantly, channel list counter is added to given index*/
00071 #ifndef DISABLE_CHANNEL_COUNTER
00072 
00073     /* Break repeating cycle when channel list counter reaches the number of channels.
00074      * Using known channel list counter and generated scramble table, create pseudo-random index that changes the repeated cycle longer.
00075      * All channels are equally used as broadcast and unicast channels
00076      *
00077      *  If number of channels is 50, number of scramble table indexes is 10 and channel dwell time is 400ms, the repeated cycle starts from beginning after 50 * 50 * 10 * 400ms = 166min
00078      */
00079     uint32_t index_tmp;
00080     uint8_t calc_tmp = (channel_list_counter / number_of_channels) % MAX_SCRAMBLE_TABLE_INDEXES;
00081     index_tmp = (uint32_t) channel_list_counter * scramble_table[calc_tmp];
00082 
00083     index_tmp += index;
00084     index_tmp %= number_of_channels;
00085     index = index_tmp;
00086 #endif /*DISABLE_CHANNEL_COUNTER*/
00087     return index;
00088 }
00089 
00090 static void fhss_generate_broadcast_start_superframe(fhss_structure_t *fhss_structure)
00091 {
00092     // If the number of superframes is low, allow broadcast on any superframe
00093     if (fhss_structure->synch_configuration.fhss_number_of_superframes < 8) {
00094         fhss_structure->broadcast_start_superframe = 0;
00095     } else {
00096         fhss_structure->broadcast_start_superframe = randLIB_get_random_in_range(0, NUMBER_OF_BC_START_SUPERFRAMES - 1);
00097     }
00098 }
00099 
00100 /**
00101  * Update channel
00102  *
00103  * This function is called by superframe handler on first(0) superframe
00104  * of every channel to resolve and change new channel.
00105  *
00106  * @param cur network interface to work on
00107  * @return true if changed to broadcast channel, false otherwise
00108  */
00109 bool fhss_change_to_next_channel(fhss_structure_t *fhss_structure)
00110 {
00111     int next_channel;
00112     bool broadcast_channel = false;
00113 
00114     uint16_t number_of_channels = fhss_structure->number_of_channels;
00115     uint8_t number_of_broadcast_channels = fhss_structure->synch_configuration.fhss_number_of_bc_channels;
00116     uint8_t unicast_channel_index = fhss_structure->uc_channel_index;
00117     uint8_t channel_index_tmp;
00118 
00119     /* Get the channel number using channel index. Latter (number_of_broadcast_channels) indexes in channel table are broadcast channels and
00120      * first (number_of_channels - number_of_broadcast_channels) are unicast channels.
00121      * In channel hopping sequence, every (number_of_channels / number_of_broadcast_channels) channel is broadcast channel and
00122      * channel hopping sequence is e.g. |uc0|uc1|uc2|bc0|uc3|uc4|uc5|bc1|uc6|...
00123      */
00124     /* Get broadcast channel */
00125     if (fhss_is_current_channel_broadcast(fhss_structure) == true) {
00126         channel_index_tmp = fhss_calc_channel_shuffle((number_of_channels - number_of_broadcast_channels) + fhss_get_bc_index(fhss_structure), fhss_structure->number_of_channels, fhss_structure->synch_configuration.fhss_number_of_bc_channels);
00127         fhss_generate_broadcast_start_superframe(fhss_structure);
00128         broadcast_channel = true;
00129     } else { /* Get unicast channel */
00130         channel_index_tmp = fhss_calc_channel_shuffle(unicast_channel_index, fhss_structure->number_of_channels, fhss_structure->synch_configuration.fhss_number_of_bc_channels);
00131         fhss_structure->uc_channel_index++;
00132         if (fhss_structure->uc_channel_index >= number_of_channels - number_of_broadcast_channels) {
00133             fhss_structure->uc_channel_index = 0;
00134         }
00135     }
00136     // Reset Beacon received flag when channel has changed
00137     fhss_structure->beacon_received_on_this_bc_channel = false;
00138     channel_index_tmp = fhss_add_channel_list_counter(channel_index_tmp, fhss_structure->number_of_channels, fhss_structure->channel_list_counter, fhss_structure->fhss_scramble_table);
00139     next_channel = channel_list_get_channel(fhss_structure->fhss_configuration.channel_mask, channel_index_tmp);
00140 
00141 #ifdef FHSS_MASSIVE_TRACE
00142     tr_debug("%"PRIu32": update, frame: %"PRIu8", channel: %d",
00143             fhss_structure->platform_functions.fhss_get_timestamp(fhss_structure->fhss_api), fhss_structure->current_superframe,
00144             next_channel);
00145 #endif
00146     fhss_structure->rx_channel = next_channel;
00147 #ifdef FHSS_CHANNEL_DEBUG
00148     if (fhss_is_current_channel_broadcast(fhss_structure) == true) {
00149         tr_info("%"PRIu32" BC %u", fhss_structure->platform_functions.fhss_get_timestamp(fhss_structure->fhss_api), next_channel);
00150     } else {
00151         tr_info("%"PRIu32" UC %u", fhss_structure->platform_functions.fhss_get_timestamp(fhss_structure->fhss_api), next_channel);
00152     }
00153 #endif /*FHSS_CHANNEL_DEBUG*/
00154     fhss_structure->callbacks.change_channel(fhss_structure->fhss_api, next_channel);
00155     return broadcast_channel;
00156 }
00157 
00158 static uint8_t fhss_get_bc_index(const fhss_structure_t *fhss_structure)
00159 {
00160     uint16_t number_of_channels = fhss_structure->number_of_channels;
00161     uint8_t number_of_bc_channels = fhss_structure->synch_configuration.fhss_number_of_bc_channels;
00162     uint8_t cur_channel_index = fhss_structure->current_channel_index;
00163 
00164     return cur_channel_index / (number_of_channels/number_of_bc_channels);
00165 }
00166 
00167 uint8_t fhss_get_offset(fhss_structure_t *fhss_structure, const uint8_t *ptr)
00168 {
00169     uint8_t i;
00170     uint8_t index = *ptr++;
00171 
00172     if (fhss_structure->number_of_channels == fhss_structure->synch_configuration.fhss_number_of_bc_channels) {
00173         // If all channels are defined as broadcast channels then return 0 to avoid division by 0.
00174         // This could happen e.g. in OTA case when fast download is needed.
00175         return 0;
00176     }
00177 
00178     // Offset to unicast channel index is calculated using XOR operation
00179     for(i=0; i<7;i++)
00180     {
00181         index ^= *ptr++;
00182     }
00183     // Offset must be < number of unicast channels
00184     index %= (fhss_structure->number_of_channels - fhss_structure->synch_configuration.fhss_number_of_bc_channels);
00185 
00186     return index;
00187 }
00188 
00189 bool fhss_is_current_channel_broadcast(fhss_structure_t *fhss_structure)
00190 {
00191     // Every channel is broadcast channel when FHSS is not enabled
00192     if (!fhss_structure) {
00193         return true;
00194     }
00195 
00196     // Should always have broadcast channels with FHSS
00197     if (!fhss_structure->synch_configuration.fhss_number_of_bc_channels) {
00198         return true;
00199     }
00200 
00201     uint8_t channel_index = fhss_structure->current_channel_index;
00202     uint16_t number_of_channels = fhss_structure->number_of_channels;
00203     uint8_t number_of_broadcast_channels = fhss_structure->synch_configuration.fhss_number_of_bc_channels;
00204 
00205     if (!(channel_index % (number_of_channels / number_of_broadcast_channels))) {
00206         return true;
00207     }
00208     return false;
00209 }
00210 
00211 static uint8_t fhss_get_destination_channel(fhss_structure_t *fhss_structure, uint8_t *destination_address)
00212 {
00213     uint8_t destination_offset;
00214     uint8_t uc_index;
00215 
00216     if (fhss_structure) {
00217         if (fhss_is_current_channel_broadcast(fhss_structure) == false) {
00218             destination_offset = fhss_get_offset(fhss_structure, destination_address);
00219             uc_index = fhss_calculate_uc_index(fhss_structure->current_channel_index, fhss_structure->number_of_channels,
00220                     fhss_structure->synch_configuration.fhss_number_of_bc_channels) + destination_offset;
00221             if (uc_index >= (fhss_structure->number_of_channels - fhss_structure->synch_configuration.fhss_number_of_bc_channels)) {
00222                 uc_index -= (fhss_structure->number_of_channels - fhss_structure->synch_configuration.fhss_number_of_bc_channels);
00223             }
00224 
00225             uc_index = fhss_calc_channel_shuffle(uc_index, fhss_structure->number_of_channels, fhss_structure->synch_configuration.fhss_number_of_bc_channels);
00226             uc_index = fhss_add_channel_list_counter(uc_index, fhss_structure->number_of_channels, fhss_structure->channel_list_counter, fhss_structure->fhss_scramble_table);
00227             return channel_list_get_channel(fhss_structure->fhss_configuration.channel_mask, uc_index);
00228         }
00229         return fhss_structure->rx_channel;
00230     }
00231     return 0;
00232 }
00233 
00234 int fhss_change_to_tx_channel(fhss_structure_t *fhss_structure, uint8_t *destination_address)
00235 {
00236     if (fhss_structure) {
00237         if (fhss_structure->fhss_state != FHSS_UNSYNCHRONIZED) {
00238             uint8_t destination_channel = fhss_get_destination_channel(fhss_structure, destination_address);
00239             fhss_structure->callbacks.change_channel(fhss_structure->fhss_api, destination_channel);
00240 #ifdef FHSS_CHANNEL_DEBUG
00241             tr_info("TX channel: %u", destination_channel);
00242 #endif /*FHSS_CHANNEL_DEBUG*/
00243         }
00244     }
00245     return 0;
00246 }
00247 
00248 int fhss_change_to_parent_channel(fhss_structure_t *fhss_structure)
00249 {
00250     uint8_t uc_index;
00251     uint8_t destination_channel;
00252     uint8_t destination_offset;
00253     if (fhss_structure) {
00254         if (fhss_structure->number_of_channels != fhss_structure->synch_configuration.fhss_number_of_bc_channels) {
00255             uint8_t parent_address[8];
00256             if (fhss_get_parent_address(fhss_structure, parent_address)) {
00257                 return -1;
00258             }
00259 
00260             destination_offset = fhss_get_offset(fhss_structure, parent_address);
00261 
00262             uc_index = fhss_calculate_uc_index(fhss_structure->current_channel_index, fhss_structure->number_of_channels,
00263                     fhss_structure->synch_configuration.fhss_number_of_bc_channels) + destination_offset;
00264             if (uc_index >= (fhss_structure->number_of_channels - fhss_structure->synch_configuration.fhss_number_of_bc_channels)) {
00265                 uc_index -= (fhss_structure->number_of_channels - fhss_structure->synch_configuration.fhss_number_of_bc_channels);
00266             }
00267             uc_index = fhss_calc_channel_shuffle(uc_index, fhss_structure->number_of_channels, fhss_structure->synch_configuration.fhss_number_of_bc_channels);
00268             uc_index = fhss_add_channel_list_counter(uc_index, fhss_structure->number_of_channels, fhss_structure->channel_list_counter, fhss_structure->fhss_scramble_table);
00269             destination_channel = channel_list_get_channel(fhss_structure->fhss_configuration.channel_mask, uc_index);
00270             fhss_structure->callbacks.change_channel(fhss_structure->fhss_api, destination_channel);
00271 #ifdef FHSS_CHANNEL_DEBUG
00272             tr_info("Parent channel: %u", destination_channel);
00273 #endif /*FHSS_CHANNEL_DEBUG*/
00274         }
00275     }
00276     return 0;
00277 }
00278 
00279 int fhss_change_to_rx_channel(fhss_structure_t *fhss_structure)
00280 {
00281     if (fhss_structure) {
00282         if (fhss_structure->fhss_state == FHSS_SYNCHRONIZED) {
00283             fhss_structure->callbacks.change_channel(fhss_structure->fhss_api, fhss_structure->rx_channel);
00284         }
00285         return 0;
00286     }
00287     return -1;
00288 }