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 {
00045     /** Start delimeter */
00046     uint8_t data_start_delimeter;
00047     /** Channel index */
00048     uint8_t channel_index;
00049     /** Sender unicast channel index */
00050     uint8_t sender_unicast_channel;
00051     /** Current superframe */
00052     uint16_t current_superframe;
00053     /** Remaining time (us) to next superframe */
00054     uint16_t remaining_slots;
00055     /** Channel list counter */
00056     uint16_t channel_list_counter;
00057     /** Hop count */
00058     uint8_t hop_count;
00059     /** Number of broadcast channels */
00060     uint8_t number_of_broadcast_channels;
00061     /** Number of TX slots per channel */
00062     uint8_t number_of_tx_slots;
00063     /** Time since last beacon (us) */
00064     uint32_t time_since_last_beacon;
00065     /** Processing delay (us) */
00066     uint16_t processing_delay;
00067     /** Superframe length */
00068     uint16_t superframe_length;
00069     /** Number of superframes per channel */
00070     uint8_t number_of_superframes_per_channel;
00071 };
00072 
00073 struct fhss_beacon_info
00074 {
00075     uint16_t pan_id;
00076     uint8_t source_address[8];
00077     uint32_t timestamp;
00078     uint8_t synch_info[FHSS_SYNCH_INFO_LENGTH];
00079     struct fhss_beacon_info *next;
00080 };
00081 
00082 struct fhss_synch_monitor
00083 {
00084     int32_t avg_synch_fix;
00085     int avg_synch_fix_counter;
00086     int drift_compensation;
00087     int channel_counter;
00088 };
00089 
00090 struct fhss_bs
00091 {
00092     uint8_t uc_channel_index;
00093     uint8_t current_superframe;
00094     uint8_t current_channel_index;
00095     uint8_t beacons_received_timer;
00096     uint8_t broadcast_start_superframe;
00097     uint8_t synch_infos_sent_counter;
00098     bool tx_allowed:1;
00099     bool send_synch_info_on_next_broadcast_channel:1;
00100     bool beacon_received_on_this_bc_channel:1;
00101     uint16_t channel_list_counter;
00102     uint16_t synch_panid;
00103     uint32_t synch_interval;
00104     struct fhss_statistics *fhss_stats_ptr;
00105     struct fhss_beacon_info *fhss_beacon_info_store;
00106     struct fhss_configuration fhss_configuration;
00107     struct fhss_synch_configuration synch_configuration;
00108     struct fhss_synch_monitor synch_monitor;
00109     uint8_t fhss_scramble_table[MAX_SCRAMBLE_TABLE_INDEXES];
00110 };
00111 
00112 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);
00113 bool fhss_is_synch_root(fhss_structure_t *fhss_structure);
00114 /**
00115  * Calculate time in microseconds to start of next superframe.
00116  *
00117  * @param fhss_struct FHSS structure
00118  * @return microseconds left to start of next superframe
00119  */
00120 uint32_t fhss_get_remaining_time_to_next_superframe(const fhss_structure_t *fhss_struct);
00121 int8_t fhss_set_synch_configuration(fhss_structure_t *fhss_structure, const fhss_synch_configuration_t *fhss_synch_configuration);
00122 int fhss_set_callbacks(fhss_structure_t *fhss_structure);
00123 uint8_t fhss_calculate_uc_index(uint8_t channel_index, uint16_t number_of_channels, uint8_t number_of_broadcast_channels);
00124 
00125 #endif /* FHSS_H_ */