fhss.h

00001 /*
00002  * Copyright (c) 2015-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 #ifndef FHSS_H_
00018 #define FHSS_H_
00019 #define MAX_SCRAMBLE_TABLE_INDEXES  20
00020 // Lifetime is given as seconds
00021 #define BEACON_INFO_LIFETIME        600
00022 // Limits the number of synchronization info messages sent on broadcast channels
00023 #define MAX_SYNCH_INFOS_PER_CHANNEL_LIST    2
00024 // FHSS randomly selects the starting superframe for broadcast channel. This defines how many superframes are used for randomization.
00025 #define NUMBER_OF_BC_START_SUPERFRAMES  3
00026 #define FHSS_MAX_ALLOWED_HOPS   254
00027 #define MAX_FHSS_TIMER_DIVIDER  100
00028 #define SYNCH_MONITOR_AVG_SAMPLES   5
00029 #define FHSS_DATA_START_DELIMETER   0x00
00030 #define FHSS_SYNCHRONIZATION_LOST   10
00031 #define BEACON_INTERVAL_INIT_DIVIDER 100
00032 #define FHSS_SYNCH_DRIFT_TOO_HIGH_LIMIT 20000
00033 #define CLOSE_TO_SUPERFRAME_LENGTH  2000
00034 #define BEACON_FIELD_SIZE(field) (sizeof((fhss_synchronization_beacon_payload_s*)0)->field)
00035 
00036 typedef struct fhss_structure fhss_structure_t;
00037 typedef struct fhss_beacon_info fhss_beacon_info_t;
00038 typedef struct fhss_synch_monitor fhss_synch_monitor_s;
00039 typedef struct fhss_failed_tx fhss_failed_tx_t;
00040 typedef struct fhss_bs fhss_bs_t;
00041 typedef struct fhss_synchronization_beacon_payload fhss_synchronization_beacon_payload_s;
00042 
00043 struct fhss_synchronization_beacon_payload {
00044     /** Start delimeter */
00045     uint8_t data_start_delimeter;
00046     /** Channel index */
00047     uint8_t channel_index;
00048     /** Sender unicast channel index */
00049     uint8_t sender_unicast_channel;
00050     /** Current superframe */
00051     uint16_t current_superframe;
00052     /** Remaining time (us) to next superframe */
00053     uint16_t remaining_slots;
00054     /** Channel list counter */
00055     uint16_t channel_list_counter;
00056     /** Hop count */
00057     uint8_t hop_count;
00058     /** Number of broadcast channels */
00059     uint8_t number_of_broadcast_channels;
00060     /** Number of TX slots per channel */
00061     uint8_t number_of_tx_slots;
00062     /** Time since last beacon (us) */
00063     uint32_t time_since_last_beacon;
00064     /** Processing delay (us) */
00065     uint16_t processing_delay;
00066     /** Superframe length */
00067     uint16_t superframe_length;
00068     /** Number of superframes per channel */
00069     uint8_t number_of_superframes_per_channel;
00070 };
00071 
00072 struct fhss_beacon_info {
00073     uint16_t pan_id;
00074     uint8_t source_address[8];
00075     uint32_t timestamp;
00076     uint8_t synch_info[FHSS_SYNCH_INFO_LENGTH];
00077     struct fhss_beacon_info *next;
00078 };
00079 
00080 struct fhss_synch_monitor {
00081     int32_t avg_synch_fix;
00082     int avg_synch_fix_counter;
00083     int drift_compensation;
00084     int channel_counter;
00085 };
00086 
00087 struct fhss_bs {
00088     uint8_t uc_channel_index;
00089     uint8_t current_superframe;
00090     uint8_t current_channel_index;
00091     uint8_t beacons_received_timer;
00092     uint8_t broadcast_start_superframe;
00093     uint8_t synch_infos_sent_counter;
00094     bool tx_allowed: 1;
00095     bool send_synch_info_on_next_broadcast_channel: 1;
00096     bool beacon_received_on_this_bc_channel: 1;
00097     uint16_t channel_list_counter;
00098     uint16_t synch_panid;
00099     uint32_t synch_interval;
00100     struct fhss_beacon_info *fhss_beacon_info_store;
00101     struct fhss_configuration fhss_configuration;
00102     struct fhss_synch_configuration synch_configuration;
00103     struct fhss_synch_monitor synch_monitor;
00104     uint8_t fhss_scramble_table[MAX_SCRAMBLE_TABLE_INDEXES];
00105 };
00106 
00107 fhss_structure_t *fhss_enable(fhss_api_t *fhss_api, const fhss_configuration_t *fhss_configuration, const fhss_timer_t *fhss_timer, fhss_statistics_t *fhss_statistics);
00108 bool fhss_is_synch_root(fhss_structure_t *fhss_structure);
00109 /**
00110  * Calculate time in microseconds to start of next superframe.
00111  *
00112  * @param fhss_struct FHSS structure
00113  * @return microseconds left to start of next superframe
00114  */
00115 uint32_t fhss_get_remaining_time_to_next_superframe(const fhss_structure_t *fhss_struct);
00116 int8_t fhss_set_synch_configuration(fhss_structure_t *fhss_structure, const fhss_synch_configuration_t *fhss_synch_configuration);
00117 int fhss_set_callbacks(fhss_structure_t *fhss_structure);
00118 uint8_t fhss_calculate_uc_index(uint8_t channel_index, uint16_t number_of_channels, uint8_t number_of_broadcast_channels);
00119 
00120 #endif /* FHSS_H_ */