FHSS WS: api function to set TX allowance level (ARMmbed#2612)

* FHSS WS: api function to set TX allowance level

* Set both TX allowance levels with single function call

Author: Jarkko Paso

nanostack/fhss_ws_extension.h

@@ -118,6 +118,27 @@ extern int ns_fhss_set_neighbor_info_fp(const fhss_api_t *fhss_api, fhss_get_nei
  */
 extern int ns_fhss_ws_set_hop_count(const fhss_api_t *fhss_api, const uint8_t hop_count);
 
+/**
+ * @brief WS TX allowance levels.
+ */
+typedef enum {
+    /** Allow transmitting only on TX slots. */
+    WS_TX_SLOT,
+    /** Allow transmitting only on TX and RX slots. */
+    WS_TX_AND_RX_SLOT,
+    /** Allow transmitting always. Also unicast on broadcast channel. */
+    WS_TX_ALWAYS
+} fhss_ws_tx_allow_level;
+
+/**
+ * @brief Set node unicast TX allowance level. Allows device to use the unicast and broadcast channel for unicast transmission as described by fhss_ws_tx_allow_level.
+ * @param fhss_api FHSS instance.
+ * @param global_level Level of TX allowance in normal mode.
+ * @param ef_level Level of TX allowance in expedited forwarding mode.
+ * @return 0 on success, -1 on fail.
+ */
+extern int ns_fhss_ws_set_tx_allowance_level(const fhss_api_t *fhss_api, const fhss_ws_tx_allow_level global_level, const fhss_ws_tx_allow_level ef_level);
+
 #ifdef __cplusplus
 }
 #endif

source/6LoWPAN/ws/ws_bootstrap.c

@@ -679,6 +679,8 @@ static int8_t ws_fhss_initialize(protocol_interface_info_entry_t *cur)
             return -1;
         }
         ns_sw_mac_fhss_register(cur->mac_api, fhss_api);
+        // Allow transmitting unicast frames only on TX slots in normal and expedited forwarding mode
+        ns_fhss_ws_set_tx_allowance_level(fhss_api, WS_TX_SLOT, WS_TX_SLOT);
     } else {
         // Read defaults from the configuration to help FHSS testing
         const fhss_ws_configuration_t *fhss_configuration_copy = ns_fhss_ws_configuration_get(fhss_api);
@@ -2652,6 +2654,13 @@ static void ws_set_fhss_hop(protocol_interface_info_entry_t *cur)
     // Calculate own hop count. This method gets inaccurate when hop count increases.
     uint8_t own_hop = (own_rank - rank_inc) / rank_inc;
     ns_fhss_ws_set_hop_count(cur->ws_info->fhss_api, own_hop);
+    if (own_hop == 1) {
+        // Allow transmitting unicast frames only on TX slots in normal mode and always in expedited forwarding mode for first hop
+        ns_fhss_ws_set_tx_allowance_level(cur->ws_info->fhss_api, WS_TX_SLOT, WS_TX_ALWAYS);
+    } else {
+        // Allow transmitting unicast frames only on TX slots in normal and expedited forwarding mode for other hops
+        ns_fhss_ws_set_tx_allowance_level(cur->ws_info->fhss_api, WS_TX_SLOT, WS_TX_SLOT);
+    }
     tr_debug("own hop: %u, own rank: %u, rank inc: %u", own_hop, own_rank, rank_inc);
 }
 

source/Service_Libs/fhss/fhss_configuration_interface.c

@@ -140,6 +140,15 @@ int ns_fhss_ws_set_hop_count(const fhss_api_t *fhss_api, const uint8_t hop_count
     return fhss_ws_set_hop_count(fhss_structure, hop_count);
 }
 
+int ns_fhss_ws_set_tx_allowance_level(const fhss_api_t *fhss_api, const fhss_ws_tx_allow_level global_level, const fhss_ws_tx_allow_level ef_level)
+{
+    fhss_structure_t *fhss_structure = fhss_get_object_with_api(fhss_api);
+    if (!fhss_structure || !fhss_structure->ws) {
+        return -1;
+    }
+    return fhss_ws_set_tx_allowance_level(fhss_structure, global_level, ef_level);
+}
+
 int ns_fhss_statistics_start(const fhss_api_t *fhss_api, fhss_statistics_t *fhss_statistics)
 {
     fhss_structure_t *fhss_structure = fhss_get_object_with_api(fhss_api);

source/Service_Libs/fhss/fhss_ws.c

@@ -169,6 +169,10 @@ fhss_structure_t *fhss_ws_enable(fhss_api_t *fhss_api, const fhss_ws_configurati
     fhss_ws_set_hop_count(fhss_struct, 0xff);
     fhss_struct->rx_channel = fhss_configuration->unicast_fixed_channel;
     fhss_struct->ws->min_synch_interval = DEFAULT_MIN_SYNCH_INTERVAL;
+    // By default, allow transmitting unicast data only on TX slots.
+    fhss_struct->ws->tx_level = WS_TX_SLOT;
+    // By default, allow always transmitting unicast data in expedited forwarding mode.
+    fhss_struct->ws->ef_tx_level = WS_TX_ALWAYS;
     ns_list_init(&fhss_struct->fhss_failed_tx_list);
     return fhss_struct;
 }
@@ -780,26 +784,26 @@ static bool fhss_ws_check_tx_time(fhss_structure_t *fhss_structure, uint16_t tx_
 
 static bool fhss_allow_transmitting_on_rx_slot(fhss_structure_t *fhss_structure)
 {
-    // This is allowed only for 1st hop devices in expedited forwarding mode
-    if (!fhss_structure->ws->expedited_forwarding_enabled_us) {
-        return false;
+    if (fhss_structure->ws->tx_level >= WS_TX_AND_RX_SLOT) {
+        return true;
     }
-    if (fhss_structure->own_hop != 1) {
-        return false;
+    // This is allowed only for devices in expedited forwarding mode
+    if (fhss_structure->ws->expedited_forwarding_enabled_us && (fhss_structure->ws->ef_tx_level >= WS_TX_AND_RX_SLOT)) {
+        return true;
     }
-    return true;
+    return false;
 }
 
 static bool fhss_allow_unicast_on_broadcast_channel(fhss_structure_t *fhss_structure)
 {
-    // This is allowed only for 1st hop devices in expedited forwarding mode
-    if (!fhss_structure->ws->expedited_forwarding_enabled_us) {
-        return false;
+    if (fhss_structure->ws->tx_level >= WS_TX_ALWAYS) {
+        return true;
     }
-    if (fhss_structure->own_hop != 1) {
-        return false;
+    // This is allowed only for devices in expedited forwarding mode
+    if (fhss_structure->ws->expedited_forwarding_enabled_us && (fhss_structure->ws->ef_tx_level >= WS_TX_ALWAYS)) {
+        return true;
     }
-    return true;
+    return false;
 }
 
 static bool fhss_ws_check_tx_conditions_callback(const fhss_api_t *api, bool is_broadcast_addr, uint8_t handle, int frame_type, uint16_t frame_length, uint8_t phy_header_length, uint8_t phy_tail_length)
@@ -1234,4 +1238,11 @@ int fhss_ws_set_hop_count(fhss_structure_t *fhss_structure, const uint8_t hop_co
     return 0;
 }
 
+int fhss_ws_set_tx_allowance_level(fhss_structure_t *fhss_structure, const fhss_ws_tx_allow_level global_level, const fhss_ws_tx_allow_level ef_level)
+{
+    fhss_structure->ws->tx_level = global_level;
+    fhss_structure->ws->ef_tx_level = ef_level;
+    return 0;
+}
+
 #endif // HAVE_WS

source/Service_Libs/fhss/fhss_ws.h

@@ -54,6 +54,8 @@ struct fhss_ws {
     bool unicast_timer_running;
     bool broadcast_timer_running;
     bool is_on_bc_channel;
+    fhss_ws_tx_allow_level tx_level;
+    fhss_ws_tx_allow_level ef_tx_level;
     struct fhss_ws_configuration fhss_configuration;
     const struct broadcast_timing_info *parent_bc_info;
     fhss_get_neighbor_info *get_neighbor_info;
@@ -65,6 +67,7 @@ int fhss_ws_set_parent(fhss_structure_t *fhss_structure, const uint8_t eui64[8],
 int fhss_ws_remove_parent(fhss_structure_t *fhss_structure, const uint8_t eui64[8]);
 int fhss_ws_configuration_set(fhss_structure_t *fhss_structure, const fhss_ws_configuration_t *fhss_configuration);
 int fhss_ws_set_hop_count(fhss_structure_t *fhss_structure, const uint8_t hop_count);
+int fhss_ws_set_tx_allowance_level(fhss_structure_t *fhss_structure, const fhss_ws_tx_allow_level global_level, const fhss_ws_tx_allow_level ef_level);
 void fhss_set_txrx_slot_length(fhss_structure_t *fhss_structure);
 
 #endif /*FHSS_WS_H_*/

source/Service_Libs/fhss/fhss_ws_empty_functions.c

@@ -80,5 +80,14 @@ int fhss_ws_set_hop_count(fhss_structure_t *fhss_structure, const uint8_t hop_co
     return -1;
 }
 
+int fhss_ws_set_tx_allowance_level(fhss_structure_t *fhss_structure, const fhss_ws_tx_allow_level global_level, const fhss_ws_tx_allow_level ef_level)
+{
+    (void) fhss_structure;
+    (void) global_level;
+    (void) ef_level;
+
+    return -1;
+}
+
 #endif // HAVE_WS
 

test/nanostack/unittest/service_libs/fhss_ws/test_fhss_ws.c

@@ -159,6 +159,8 @@ static fhss_api_t *test_generate_fhss_api(void)
     fhss_common_stub.fhss_struct.fhss_state = FHSS_UNSYNCHRONIZED;
     fhss_common_stub.fhss_struct.own_hop = 0xff;
     fhss_common_stub.fhss_struct.ws->is_on_bc_channel = false;
+    fhss_common_stub.fhss_struct.ws->tx_level = WS_TX_SLOT;
+    fhss_common_stub.fhss_struct.ws->ef_tx_level = WS_TX_ALWAYS;
     fhss_common_stub.fhss_struct.callbacks.change_channel = &mac_set_channel;
     fhss_common_stub.fhss_struct.callbacks.read_mac_address = &mac_read_64bit_mac_address;
     fhss_common_stub.fhss_struct.callbacks.read_tx_queue_size = &mac_read_tx_queue_sizes;
@@ -354,6 +356,7 @@ bool test_fhss_ws_tx_handle_callback()
     }
     // Test TX allowed on RX slot for 1st hop in expedited forwarding mode
     fhss_common_stub.fhss_struct.ws->is_on_bc_channel = false;
+    fhss_ws_set_tx_allowance_level(&fhss_common_stub.fhss_struct, WS_TX_SLOT, WS_TX_AND_RX_SLOT);
     fhss_common_stub.fhss_struct.own_hop = 1;
     fhss_common_stub.fhss_struct.ws->expedited_forwarding_enabled_us = 1000000;
     fhss_common_stub.fhss_struct.ws->fhss_configuration.fhss_broadcast_interval = 1020;
@@ -378,6 +381,7 @@ bool test_fhss_ws_tx_handle_callback()
     }
     // Test TX allowed on broadcast channel for 1st hop in expedited forwarding mode
     fhss_common_stub.fhss_struct.ws->is_on_bc_channel = true;
+    fhss_ws_set_tx_allowance_level(&fhss_common_stub.fhss_struct, WS_TX_SLOT, WS_TX_ALWAYS);
     fhss_common_stub.fhss_struct.own_hop = 1;
     fhss_common_stub.fhss_struct.ws->expedited_forwarding_enabled_us = 1000000;
     fhss_common_stub.fhss_struct.ws->fhss_configuration.fhss_broadcast_interval = 1020;
@@ -390,6 +394,7 @@ bool test_fhss_ws_tx_handle_callback()
     }
     // Test TX not allowed on broadcast channel for 2nd hop in expedited forwarding mode
     fhss_common_stub.fhss_struct.ws->is_on_bc_channel = true;
+    fhss_ws_set_tx_allowance_level(&fhss_common_stub.fhss_struct, WS_TX_SLOT, WS_TX_SLOT);
     fhss_common_stub.fhss_struct.own_hop = 2;
     fhss_common_stub.fhss_struct.ws->expedited_forwarding_enabled_us = 1000000;
     if (fhss_common_stub.fhss_struct.fhss_api->tx_handle(api, DEFAULT_IS_BC_DEST, dest_address, DEFAULT_FRAME_TYPE, DEFAULT_FRAME_LENGTH, DEFAULT_PHY_HEAD_LENGTH, DEFAULT_PHY_TAIL_LENGTH, DEFAULT_TX_TIME) != -3) {
@@ -487,6 +492,7 @@ bool test_fhss_ws_check_tx_conditions_callback()
     }
     // Test TX allowed on RX slot for 1st hop in expedited forwarding mode
     fhss_common_stub.fhss_struct.own_hop = 1;
+    fhss_ws_set_tx_allowance_level(&fhss_common_stub.fhss_struct, WS_TX_SLOT, WS_TX_AND_RX_SLOT);
     fhss_common_stub.fhss_struct.ws->expedited_forwarding_enabled_us = 1000000;
     fhss_common_stub.fhss_struct.ws->fhss_configuration.fhss_broadcast_interval = 1020;
     fhss_common_stub.fhss_struct.ws->fhss_configuration.fhss_bc_dwell_interval = 255;
@@ -504,6 +510,7 @@ bool test_fhss_ws_check_tx_conditions_callback()
     }
     // Test TX not allowed on RX slot for 2nd hop in expedited forwarding mode
     fhss_common_stub.fhss_struct.own_hop = 2;
+    fhss_ws_set_tx_allowance_level(&fhss_common_stub.fhss_struct, WS_TX_SLOT, WS_TX_SLOT);
     fhss_common_stub.fhss_struct.ws->expedited_forwarding_enabled_us = 1000000;
     fhss_platform_stub.remaining_slots_value = 700000;
     if (fhss_common_stub.fhss_struct.fhss_api->check_tx_conditions(api, DEFAULT_IS_BC_DEST, DEFAULT_HANDLE, DEFAULT_FRAME_TYPE, DEFAULT_FRAME_LENGTH, DEFAULT_PHY_HEAD_LENGTH, DEFAULT_PHY_TAIL_LENGTH) != false) {
@@ -526,6 +533,7 @@ bool test_fhss_ws_check_tx_conditions_callback()
     }
     // Test TX allowed on broadcast channel for 1st hop in expedited forwarding mode
     fhss_common_stub.fhss_struct.own_hop = 1;
+    fhss_ws_set_tx_allowance_level(&fhss_common_stub.fhss_struct, WS_TX_SLOT, WS_TX_ALWAYS);
     fhss_common_stub.fhss_struct.ws->is_on_bc_channel = true;
     fhss_common_stub.fhss_struct.ws->expedited_forwarding_enabled_us = 1000000;
     fhss_common_stub.fhss_struct.ws->fhss_configuration.fhss_broadcast_interval = 1020;
@@ -538,12 +546,14 @@ bool test_fhss_ws_check_tx_conditions_callback()
     }
     // Test TX not allowed on broadcast channel for 2nd hop in expedited forwarding mode
     fhss_common_stub.fhss_struct.own_hop = 2;
+    fhss_ws_set_tx_allowance_level(&fhss_common_stub.fhss_struct, WS_TX_SLOT, WS_TX_SLOT);
     if (fhss_common_stub.fhss_struct.fhss_api->check_tx_conditions(api, DEFAULT_IS_BC_DEST, DEFAULT_HANDLE, DEFAULT_FRAME_TYPE, DEFAULT_FRAME_LENGTH, DEFAULT_PHY_HEAD_LENGTH, DEFAULT_PHY_TAIL_LENGTH) != false) {
         printf("Fail: TX conditions, 2nd hop, EF enabled on BC\r\n");
         return false;
     }
     // Test TX not allowed on broadcast channel for 1st hop when expedited forwarding mode disabled
     fhss_common_stub.fhss_struct.own_hop = 1;
+    fhss_ws_set_tx_allowance_level(&fhss_common_stub.fhss_struct, WS_TX_SLOT, WS_TX_ALWAYS);
     fhss_common_stub.fhss_struct.ws->expedited_forwarding_enabled_us = 0;
     if (fhss_common_stub.fhss_struct.fhss_api->check_tx_conditions(api, DEFAULT_IS_BC_DEST, DEFAULT_HANDLE, DEFAULT_FRAME_TYPE, DEFAULT_FRAME_LENGTH, DEFAULT_PHY_HEAD_LENGTH, DEFAULT_PHY_TAIL_LENGTH) != false) {
         printf("Fail: TX conditions, 1st hop, EF disabled on BC\r\n");
@@ -940,6 +950,7 @@ bool test_fhss_ws_get_retry_period_callback()
     }
     // Test retrying allowed on RX slot for 1st hop in expedited forwarding mode
     fhss_common_stub.fhss_struct.own_hop = 1;
+    fhss_ws_set_tx_allowance_level(&fhss_common_stub.fhss_struct, WS_TX_SLOT, WS_TX_ALWAYS);
     fhss_common_stub.fhss_struct.ws->expedited_forwarding_enabled_us = 1000000;
     fhss_common_stub.fhss_struct.ws->fhss_configuration.fhss_broadcast_interval = 1020;
     fhss_common_stub.fhss_struct.ws->fhss_configuration.fhss_bc_dwell_interval = 255;
@@ -955,6 +966,7 @@ bool test_fhss_ws_get_retry_period_callback()
     }
     // Test retrying not allowed on RX slot for 2nd hop in expedited forwarding mode
     fhss_common_stub.fhss_struct.own_hop = 2;
+    fhss_ws_set_tx_allowance_level(&fhss_common_stub.fhss_struct, WS_TX_SLOT, WS_TX_SLOT);
     fhss_platform_stub.remaining_slots_value = 700000;
     retry_period = fhss_common_stub.fhss_struct.fhss_api->get_retry_period(api, NULL, 0);
     if (retry_period != 70000) {

test/nanostack/unittest/stub/fhss_ws_stub.c

@@ -58,3 +58,8 @@ int fhss_ws_set_hop_count(fhss_structure_t *fhss_structure, const uint8_t hop_co
 {
     return 0;
 }
+
+int fhss_ws_set_tx_allowance_level(fhss_structure_t *fhss_structure, const fhss_ws_tx_allow_level global_level, const fhss_ws_tx_allow_level ef_level)
+{
+    return 0;
+}