fhss_channel.c

00001 /*
00002  * Copyright (c) 2016-2018, 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_common.h"
00023 #include "fhss_channel.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->bs->synch_configuration.fhss_number_of_superframes < 8) {
00094         fhss_structure->bs->broadcast_start_superframe = 0;
00095     } else {
00096         fhss_structure->bs->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->bs->synch_configuration.fhss_number_of_bc_channels;
00116     uint8_t unicast_channel_index = fhss_structure->bs->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->bs->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->bs->synch_configuration.fhss_number_of_bc_channels);
00131         if (++fhss_structure->bs->uc_channel_index >= number_of_channels - number_of_broadcast_channels) {
00132             fhss_structure->bs->uc_channel_index = 0;
00133         }
00134     }
00135     // Reset Beacon received flag when channel has changed
00136     fhss_structure->bs->beacon_received_on_this_bc_channel = false;
00137     channel_index_tmp = fhss_add_channel_list_counter(channel_index_tmp, fhss_structure->number_of_channels, fhss_structure->bs->channel_list_counter, fhss_structure->bs->fhss_scramble_table);
00138     next_channel = channel_list_get_channel(fhss_structure->bs->fhss_configuration.channel_mask, channel_index_tmp);
00139 
00140     fhss_structure->rx_channel = next_channel;
00141 #ifdef FHSS_CHANNEL_DEBUG
00142     if (fhss_is_current_channel_broadcast(fhss_structure) == true) {
00143         tr_info("%"PRIu32" BC %u", fhss_structure->platform_functions.fhss_get_timestamp(fhss_structure->fhss_api), next_channel);
00144     } else {
00145         tr_info("%"PRIu32" UC %u", fhss_structure->platform_functions.fhss_get_timestamp(fhss_structure->fhss_api), next_channel);
00146     }
00147 #endif /*FHSS_CHANNEL_DEBUG*/
00148     fhss_structure->callbacks.change_channel(fhss_structure->fhss_api, next_channel);
00149     return broadcast_channel;
00150 }
00151 
00152 static uint8_t fhss_get_bc_index(const fhss_structure_t *fhss_structure)
00153 {
00154     uint16_t number_of_channels = fhss_structure->number_of_channels;
00155     uint8_t number_of_bc_channels = fhss_structure->bs->synch_configuration.fhss_number_of_bc_channels;
00156     uint8_t cur_channel_index = fhss_structure->bs->current_channel_index;
00157 
00158     return cur_channel_index / (number_of_channels/number_of_bc_channels);
00159 }
00160 
00161 uint8_t fhss_get_offset(fhss_structure_t *fhss_structure, const uint8_t *ptr)
00162 {
00163     uint8_t i;
00164     uint8_t index = *ptr++;
00165 
00166     if (fhss_structure->number_of_channels == fhss_structure->bs->synch_configuration.fhss_number_of_bc_channels) {
00167         // If all channels are defined as broadcast channels then return 0 to avoid division by 0.
00168         // This could happen e.g. in OTA case when fast download is needed.
00169         return 0;
00170     }
00171 
00172     // Offset to unicast channel index is calculated using XOR operation
00173     for(i=0; i<7;i++)
00174     {
00175         index ^= *ptr++;
00176     }
00177     // Offset must be < number of unicast channels
00178     index %= (fhss_structure->number_of_channels - fhss_structure->bs->synch_configuration.fhss_number_of_bc_channels);
00179 
00180     return index;
00181 }
00182 
00183 bool fhss_is_current_channel_broadcast(fhss_structure_t *fhss_structure)
00184 {
00185     // Every channel is broadcast channel when FHSS is not enabled
00186     if (!fhss_structure) {
00187         return true;
00188     }
00189 
00190     // Should always have broadcast channels with FHSS
00191     if (!fhss_structure->bs->synch_configuration.fhss_number_of_bc_channels) {
00192         return true;
00193     }
00194 
00195     uint8_t channel_index = fhss_structure->bs->current_channel_index;
00196     uint16_t number_of_channels = fhss_structure->number_of_channels;
00197     uint8_t number_of_broadcast_channels = fhss_structure->bs->synch_configuration.fhss_number_of_bc_channels;
00198 
00199     if (!(channel_index % (number_of_channels / number_of_broadcast_channels))) {
00200         return true;
00201     }
00202     return false;
00203 }
00204 
00205 static uint8_t fhss_get_destination_channel(fhss_structure_t *fhss_structure, uint8_t *destination_address)
00206 {
00207     uint8_t destination_offset;
00208     uint8_t uc_index;
00209 
00210     if (fhss_structure) {
00211         if (fhss_is_current_channel_broadcast(fhss_structure) == false) {
00212             destination_offset = fhss_get_offset(fhss_structure, destination_address);
00213             uc_index = fhss_calculate_uc_index(fhss_structure->bs->current_channel_index, fhss_structure->number_of_channels,
00214                     fhss_structure->bs->synch_configuration.fhss_number_of_bc_channels) + destination_offset;
00215             if (uc_index >= (fhss_structure->number_of_channels - fhss_structure->bs->synch_configuration.fhss_number_of_bc_channels)) {
00216                 uc_index -= (fhss_structure->number_of_channels - fhss_structure->bs->synch_configuration.fhss_number_of_bc_channels);
00217             }
00218 
00219             uc_index = fhss_calc_channel_shuffle(uc_index, fhss_structure->number_of_channels, fhss_structure->bs->synch_configuration.fhss_number_of_bc_channels);
00220             uc_index = fhss_add_channel_list_counter(uc_index, fhss_structure->number_of_channels, fhss_structure->bs->channel_list_counter, fhss_structure->bs->fhss_scramble_table);
00221             return channel_list_get_channel(fhss_structure->bs->fhss_configuration.channel_mask, uc_index);
00222         }
00223         return fhss_structure->rx_channel;
00224     }
00225     return 0;
00226 }
00227 
00228 int fhss_change_to_tx_channel(fhss_structure_t *fhss_structure, uint8_t *destination_address)
00229 {
00230     if (fhss_structure) {
00231         if (fhss_structure->fhss_state != FHSS_UNSYNCHRONIZED) {
00232             uint8_t destination_channel = fhss_get_destination_channel(fhss_structure, destination_address);
00233             fhss_structure->callbacks.change_channel(fhss_structure->fhss_api, destination_channel);
00234 #ifdef FHSS_CHANNEL_DEBUG
00235             tr_info("TX channel: %u", destination_channel);
00236 #endif /*FHSS_CHANNEL_DEBUG*/
00237         }
00238     }
00239     return 0;
00240 }
00241 
00242 int fhss_change_to_parent_channel(fhss_structure_t *fhss_structure)
00243 {
00244     uint8_t uc_index;
00245     uint8_t destination_channel;
00246     uint8_t destination_offset;
00247     if (fhss_structure) {
00248         if (fhss_structure->number_of_channels != fhss_structure->bs->synch_configuration.fhss_number_of_bc_channels) {
00249             uint8_t parent_address[8];
00250             if (fhss_get_parent_address(fhss_structure, parent_address)) {
00251                 return -1;
00252             }
00253 
00254             destination_offset = fhss_get_offset(fhss_structure, parent_address);
00255 
00256             uc_index = fhss_calculate_uc_index(fhss_structure->bs->current_channel_index, fhss_structure->number_of_channels,
00257                     fhss_structure->bs->synch_configuration.fhss_number_of_bc_channels) + destination_offset;
00258             if (uc_index >= (fhss_structure->number_of_channels - fhss_structure->bs->synch_configuration.fhss_number_of_bc_channels)) {
00259                 uc_index -= (fhss_structure->number_of_channels - fhss_structure->bs->synch_configuration.fhss_number_of_bc_channels);
00260             }
00261             uc_index = fhss_calc_channel_shuffle(uc_index, fhss_structure->number_of_channels, fhss_structure->bs->synch_configuration.fhss_number_of_bc_channels);
00262             uc_index = fhss_add_channel_list_counter(uc_index, fhss_structure->number_of_channels, fhss_structure->bs->channel_list_counter, fhss_structure->bs->fhss_scramble_table);
00263             destination_channel = channel_list_get_channel(fhss_structure->bs->fhss_configuration.channel_mask, uc_index);
00264             fhss_structure->callbacks.change_channel(fhss_structure->fhss_api, destination_channel);
00265 #ifdef FHSS_CHANNEL_DEBUG
00266             tr_info("Parent channel: %u", destination_channel);
00267 #endif /*FHSS_CHANNEL_DEBUG*/
00268         }
00269     }
00270     return 0;
00271 }
00272 
00273 int fhss_change_to_rx_channel(fhss_structure_t *fhss_structure)
00274 {
00275     if (fhss_structure) {
00276         if (fhss_structure->fhss_state == FHSS_SYNCHRONIZED) {
00277             fhss_structure->callbacks.change_channel(fhss_structure->fhss_api, fhss_structure->rx_channel);
00278         }
00279         return 0;
00280     }
00281     return -1;
00282 }