fhss_beacon.h

00001 /*
00002  * Copyright (c) 2015-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 #ifndef __FHSS_BEACON_H__
00018 #define __FHSS_BEACON_H__
00019 
00020 #ifdef __cplusplus
00021 extern "C" {
00022 #endif
00023 
00024 #include <stdint.h>
00025 
00026 #define FHSS_DATA_START_DELIMETER   0x00
00027 
00028 #define FHSS_SYNCH_BEACON_LIMIT     2
00029 #define FHSS_STOP_SENDING_BEACONS   8
00030 #define FHSS_SYNCHRONIZATION_LOST   10
00031 
00032 // Based on datarate and Beacon frame packet length 71 bytes
00033 #define BEACON_TX_TIME              (1000000 / (dev_get_phy_datarate(cur) / 8) * 71)
00034 
00035 #define BEACON_INTERVAL_INIT_DIVIDER 100
00036 #define FHSS_SYNCH_DRIFT_TOO_HIGH_LIMIT 20000
00037 #define CLOSE_TO_SUPERFRAME_LENGTH  2000
00038 
00039 /** beacon synchronization info */
00040 typedef struct {
00041     /** Start delimeter */
00042     uint8_t data_start_delimeter;
00043 
00044     /** Channel index */
00045     uint8_t channel_index;
00046 
00047     /** Sender unicast channel index */
00048     uint8_t sender_unicast_channel;
00049 
00050     /** Current superframe */
00051     uint16_t current_superframe;
00052 
00053     /** Remaining time (us) to next superframe */
00054     uint16_t remaining_slots;
00055 
00056     /** Channel list counter */
00057     uint16_t channel_list_counter;
00058 
00059     /** Hop count */
00060     uint8_t hop_count;
00061 
00062     /** Number of broadcast channels */
00063     uint8_t number_of_broadcast_channels;
00064 
00065     /** Number of TX slots per channel */
00066     uint8_t number_of_tx_slots;
00067 
00068     /** Time since last beacon (us) */
00069     uint32_t time_since_last_beacon;
00070 
00071     /** Processing delay (us) */
00072     uint16_t processing_delay;
00073 
00074     /** Superframe length */
00075     uint16_t superframe_length;
00076 
00077     /** Number of superframes per channel */
00078     uint8_t number_of_superframes_per_channel;
00079 
00080 } fhss_synchronization_beacon_payload_s;
00081 
00082 
00083 #define BEACON_FIELD_SIZE(field) (sizeof((fhss_synchronization_beacon_payload_s*)0)->field)
00084 
00085 // Calculate the size of data encoded from fhss_synchronization_beacon_payload_s,
00086 // please add new items from that struct to this macro to keep code working.
00087 #define FHSS_SYNC_BEACON_PAYLOAD_SYNC_SIZE \
00088     (BEACON_FIELD_SIZE(data_start_delimeter) + \
00089     BEACON_FIELD_SIZE(channel_index) + \
00090     BEACON_FIELD_SIZE(sender_unicast_channel) + \
00091     BEACON_FIELD_SIZE(current_superframe) + \
00092     BEACON_FIELD_SIZE(remaining_slots) + \
00093     BEACON_FIELD_SIZE(channel_list_counter) + \
00094     BEACON_FIELD_SIZE(hop_count) + \
00095     BEACON_FIELD_SIZE(number_of_broadcast_channels) + \
00096     BEACON_FIELD_SIZE(number_of_tx_slots) + \
00097     BEACON_FIELD_SIZE(time_since_last_beacon) + \
00098     BEACON_FIELD_SIZE(processing_delay) + \
00099     BEACON_FIELD_SIZE(superframe_length) + \
00100     BEACON_FIELD_SIZE(number_of_superframes_per_channel))
00101 
00102 // 1 byte for protocol id,
00103 // 1 byte for accept join
00104 // 16 bytes for network id, TODO: find proper define to replace this magic value
00105 #define FHSS_SYNC_BEACON_PAYLOAD_PREFIX_SIZE (1 + 1 + 16)
00106 
00107 // this counts the common prefix and the fhss specific sync payload
00108 #define FHSS_SYNC_BEACON_PAYLOAD_COMPLETE_SIZE \
00109     (FHSS_SYNC_BEACON_PAYLOAD_PREFIX_SIZE + FHSS_SYNC_BEACON_PAYLOAD_SYNC_SIZE)
00110 
00111 
00112 int fhss_beacon_periodic_start(fhss_structure_t *fhss_structure, uint32_t time_to_first_beacon);
00113 void fhss_beacon_periodic_stop(fhss_structure_t *fhss_structure);
00114 
00115 void fhss_beacon_build(fhss_structure_t *fhss_structure, uint8_t *dest);
00116 
00117 /**
00118  * Encode the given beacon syncronization structure into given buffer.
00119  *
00120  * Note: this information will not include protocol-id, accept_join or network-id
00121  *
00122  * @param buffer target buffer, must be at least FHSS_SYNC_BEACON_PAYLOAD_SIZE in size
00123  * @param source source synchronization data to be encoded
00124  * @return pointer to one byte after the encoded data
00125  */
00126 uint8_t* fhss_beacon_encode_raw(uint8_t *buffer, const fhss_synchronization_beacon_payload_s *source);
00127 
00128 /**
00129  * Decode the given beacon syncronization structure from given buffer and process the data.
00130  *
00131  * @param protocol_id protocol id from beacon payload
00132  * @param accept_join accept join from beacon payload
00133  * @param network_id network id from beacon payload, 16 bytes in size
00134  * @param dest decoded data
00135  * @param buffer source buffer, must be at least FHSS_SYNC_BEACON_PAYLOAD_SIZE in size
00136  * @param elapsed_time time since previous beacon
00137  * @param number_of_channels number of channels
00138  */
00139 void fhss_beacon_decode(fhss_synchronization_beacon_payload_s *dest, const uint8_t *buffer, uint32_t elapsed_time, uint16_t number_of_channels);
00140 
00141 /**
00142  * Decode the beacon data as-is to the given struct.
00143  * 
00144  * @param dest decoded data
00145  * @param buffer source buffer, must be at least FHSS_SYNC_BEACON_PAYLOAD_SIZE in size
00146  */
00147 void fhss_beacon_decode_raw(fhss_synchronization_beacon_payload_s* dest, const uint8_t* buffer);
00148 
00149 int fhss_beacon_update_payload(fhss_structure_t *fhss_structure,
00150                                 fhss_synchronization_beacon_payload_s *payload);
00151 
00152 void fhss_beacon_received(fhss_structure_t *fhss_structure, const uint8_t *synch_info, const uint32_t elapsed_time);
00153 
00154 /**
00155  * This function is called whenever a node receives a beacon in the "proper state".
00156  * The implmentation of it stores the data received and eventually synchronizes
00157  * itself.
00158  *
00159  * Note: this is in completely illogical header file, but we have a
00160  * circular dependency with net_fhss.h and protocol.h.
00161  *
00162  * @param cur the network interface which received beacon
00163  * @param payload decoded beacon payload information
00164  *
00165  * @return 0 on success
00166  */
00167 int fhss_sync_with_beacon(fhss_structure_t *fhss_structure,
00168                           const fhss_synchronization_beacon_payload_s *payload);
00169 
00170 uint8_t fhss_calculate_uc_index(uint8_t channel_index, uint16_t number_of_channels, uint8_t number_of_broadcast_channels);
00171 int8_t fhss_beacon_create_tasklet(fhss_structure_t *fhss_structure);
00172 
00173 #ifdef __cplusplus
00174 }
00175 #endif
00176 
00177 #endif // !__FHSS_BEACON_H__