Skip to content

Commit 5a8c63a

Browse files
0xc01700xc0170
authored
Merge pull request #7996 from JuhPuur/feature_mactester
Add nanostack mac tester and testcases
2 parents 4fbd39c + 39328af commit 5a8c63a

File tree

18 files changed

+2680
-3
lines changed

18 files changed

+2680
-3
lines changed

‎TEST_APPS/device/nanostack_mac_tester/README.md

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Nanostack MAC test application
2+
3+
You can use this application to test the Nanostack RF driver implementations that follow the [Nanostack RF driver porting instructions](https://os.mbed.com/docs/v5.6/reference/contributing-connectivity.html#porting-new-rf-driver-for-6lowpan-stack). The application has a command-line interface that is used to send commands to Nanostack's MAC layer, for example starting PANs, scanning or sending data. The provided tests do not test performance or stability and only indirectly test RF functionalities.
4+
5+
## Table of contents
6+
7+
* [Prerequisites](#prerequisites)
8+
* [Setting up the application](#setting-up-the-application)
9+
* [Application usage](#application-usage)
10+
* [Interactive mode](#interactive-mode)
11+
* [Automated mode](#automated-mode)
12+
* [Testcases](#testcases)
13+
* [Considerations](#considerations)
14+
15+
## Prerequisites
16+
17+
* [Mbed CLI](https://github.com/ARMmbed/mbed-cli).
18+
* Mbed OS target board with build in radio, OR RF shield with Mbed OS driver
19+
20+
## Setting up the application
21+
22+
### Add your RF driver
23+
24+
When using RF shield, you need to configure it to be a default RF driver and instruct Mbed OS that RF driver is present. For example, configuring Atmel RF driver to provide default driver:
25+
26+
```
27+
"target_overrides": {
28+
"*": {
29+
"target.device_has_add": ["802_15_4_RF_PHY"],
30+
"atmel-rf.provide-default": true
31+
```
32+
33+
### Checking platform support
34+
35+
Check that your choice of platform is supported by your choice of toolchain:
36+
37+
```
38+
mbed compile --supported
39+
```
40+
41+
<span class="notes">**Note:** Targets are often abbreviated from the full model names. In the case of `FRDM-K64F` the target is `K64F`.</span>
42+
43+
## Run tests
44+
45+
You can use this application in interactive or automated mode.
46+
47+
### Interactive mode
48+
49+
To set the application to interactive mode:
50+
51+
1. Build the application.
52+
```
53+
mbed test --compile --icetea -t TOOLCHAIN -m TARGET_PLATFORM -DICETEA_MAC_TESTER_ENABLED --test-config NANOSTACK_MAC_TESTER -n address_read_and_write,send_data,send_data_indirect,send_large_payloads,create_and_join_PAN,ED_scan
54+
```
55+
2. Connect your board and copy the compiled application binary from the `BUILD/tests/TARGET_PLATFORM/TOOLCHAIN/TEST_APPS/device/nanostack_mac_tester/` folder to the board.
56+
3. Wait for the device to flash the binary.
57+
4. Open a serial connection with a program such as PuTTY, screen or minicom. The default baudrate is 115200.
58+
5. Press the reset button on the board. The Arm Mbed logo and trace appears in the terminal window.
59+
60+
If the driver registration and SW MAC creation was successful, the application is ready to receive commands.
61+
62+
To start off, type `help` to list all commands available and furthermore `help <command>` to print detailed information about a specific command.
63+
64+
### Automated mode
65+
66+
```
67+
mbed test --clean --compile --run --icetea -t TOOLCHAIN -m TARGET_PLATFORM -DICETEA_MAC_TESTER_ENABLED --test-config NANOSTACK_MAC_TESTER -n address_read_and_write,send_data,send_data_indirect,send_large_payloads,create_and_join_PAN,ED_scan
68+
```
69+
70+
Many of the provided testcases have a `self.channel` variable in the `setUp()` function for setting the RF channel. The default channel is 11. If you wish to run a test on another channel, you will need to change it manually in TEST_APPS/testcases/nanostack_mac_tester/.
71+
72+
Some testcases also use a secondary channel for transmitting and will use the next higher channel for that purpose. If the given channel is 26, the secondary channel will default to 25.
73+
74+
### Test cases
75+
76+
The automated test set runs the following testcases included in the repository under `TEST_APPS/testcases/nanostack_mac_tester/`.
77+
* Create and join PAN
78+
* Direct data transmission(Transmission between two devices)
79+
* Indirect data transmission(Transmission between two devices with one device acting as intermediary)
80+
* ED scan(Energy Density scanning)
81+
* Address read and write
82+
* Large data transmission
83+
84+
### Considerations
85+
86+
* Devices need to be power cycled if they are unresponsive to test framework commands even after resetting.
87+
* Devices can be enclosed in an RF isolation box to improve the consistency of test results.
88+
* Some boards and radio modules come with a PCB trace antenna, instead of an SMD antenna, and need to be spaced further apart to decrease interference.

‎TEST_APPS/device/nanostack_mac_tester/main.cpp

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
/*
2+
* Copyright (c) 2017, Arm Limited and affiliates.
3+
* SPDX-License-Identifier: Apache-2.0
4+
*
5+
* Licensed under the Apache License, Version 2.0 (the "License");
6+
* you may not use this file except in compliance with the License.
7+
* You may obtain a copy of the License at
8+
*
9+
* http://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*/
17+
#include "mbed.h"
18+
#include "rtos.h"
19+
#include "sw_mac.h"
20+
#include "ns_hal_init.h"
21+
#define MBED_CMDLINE_MAX_LINE_LENGTH 250
22+
#include "ns_cmdline.h"
23+
24+
#include "mac_commands.h"
25+
26+
#define HEAP_FOR_MAC_TESTER_SIZE 10000
27+
#define RX_BUFFER_SIZE 512
28+
29+
#define ATMEL 1
30+
#define MCR20 2
31+
#define OTHER 3
32+
33+
#define TRACE_GROUP "Main"
34+
#include "mbed-trace/mbed_trace.h"
35+
36+
#include "NanostackRfPhy.h"
37+
38+
#if !DEVICE_802_15_4_PHY
39+
#error [NOT_SUPPORTED] No 802.15.4 RF driver found for this target
40+
#endif
41+
42+
#ifndef ICETEA_MAC_TESTER_ENABLED
43+
#error [NOT_SUPPORTED] Skipping Nanostack MAC tester application.
44+
#endif
45+
46+
extern mac_api_s *mac_interface;
47+
RawSerial pc(USBTX, USBRX);
48+
osThreadId main_thread;
49+
static CircularBuffer<uint8_t, RX_BUFFER_SIZE> rx_buffer;
50+
static uint8_t ns_heap[HEAP_FOR_MAC_TESTER_SIZE];
51+
52+
static void app_heap_error_handler(heap_fail_t event)
53+
{
54+
tr_error("Heap error (%d), app_heap_error_handler()", event);
55+
switch (event) {
56+
case NS_DYN_MEM_NULL_FREE:
57+
case NS_DYN_MEM_DOUBLE_FREE:
58+
case NS_DYN_MEM_ALLOCATE_SIZE_NOT_VALID:
59+
case NS_DYN_MEM_POINTER_NOT_VALID:
60+
case NS_DYN_MEM_HEAP_SECTOR_CORRUPTED:
61+
case NS_DYN_MEM_HEAP_SECTOR_UNITIALIZED:
62+
break;
63+
default:
64+
break;
65+
}
66+
while (1);
67+
}
68+
69+
static void rx_interrupt(void)
70+
{
71+
uint8_t c = pc.getc();
72+
rx_buffer.push(c);
73+
if (main_thread != NULL) {
74+
osSignalSet(main_thread, 1);
75+
}
76+
}
77+
78+
static void handle_rx_data(void)
79+
{
80+
bool exit = false;
81+
uint8_t data;
82+
83+
while (1) {
84+
exit = !rx_buffer.pop(data);
85+
if (exit) {
86+
break;
87+
}
88+
cmd_char_input(data);
89+
}
90+
}
91+
92+
93+
static int mac_prepare(void)
94+
{
95+
NanostackRfPhy &rf_phy = NanostackRfPhy::get_default_instance();
96+
int8_t rf_driver_id = rf_phy.rf_register();
97+
uint8_t rf_eui64[8];
98+
99+
if (rf_driver_id < 0) {
100+
tr_error("Failed to register RF driver.");
101+
return -1;
102+
}
103+
rf_phy.get_mac_address(rf_eui64);
104+
mac_description_storage_size_t mac_description;
105+
mac_description.device_decription_table_size = DEVICE_DESCRIPTOR_TABLE_SIZE; /** MAC Device description list size */
106+
mac_description.key_description_table_size = KEY_DESCRIPTOR_TABLE_SIZE; /** MAC Key description list size */
107+
mac_description.key_lookup_size = LOOKUP_DESCRIPTOR_TABLE_SIZE; /** Key description key lookup list size */
108+
mac_description.key_usage_size = USAGE_DESCRIPTOR_TABLE_SIZE; /** Key description key usage list size */
109+
tr_info("Registered RF driver with id: %hhu, EUI64: %s", rf_driver_id, mbed_trace_array(rf_eui64, 8));
110+
mac_interface = ns_sw_mac_create(rf_driver_id, &mac_description);
111+
if (!mac_interface) {
112+
tr_error("Failed to create SW MAC.");
113+
return -2;
114+
}
115+
116+
return mac_interface->mac_initialize(mac_interface, mac_data_confirm_handler,
117+
mac_data_indication_handler, mac_purge_confirm_handler, mac_mlme_confirm_handler,
118+
mac_mlme_indication_handler, rf_driver_id);
119+
}
120+
121+
static void cmd_ready_cb(int retcode)
122+
{
123+
cmd_next(retcode);
124+
}
125+
126+
static void trace_printer(const char *str)
127+
{
128+
printf("%s\n", str);
129+
cmd_output();
130+
fflush(stdout);
131+
}
132+
133+
int main(void)
134+
{
135+
main_thread = osThreadGetId();
136+
pc.baud(MBED_CONF_PLATFORM_STDIO_BAUD_RATE);
137+
pc.attach(rx_interrupt);
138+
ns_hal_init(ns_heap, HEAP_FOR_MAC_TESTER_SIZE, app_heap_error_handler, NULL);
139+
mbed_trace_init();
140+
mbed_trace_print_function_set(trace_printer);
141+
cmd_init(&default_cmd_response_out);
142+
cmd_set_ready_cb(cmd_ready_cb);
143+
mac_commands_init();
144+
145+
if (mac_prepare() != 0) {
146+
return -1;
147+
}
148+
tr_info("Created driver & SW MAC");
149+
150+
while (true) {
151+
osEvent os_event = Thread::signal_wait(1);
152+
if (os_event.status != osEventSignal) {
153+
osThreadYield();
154+
} else {
155+
handle_rx_data();
156+
}
157+
}
158+
return 0;
159+
}

‎TEST_APPS/device/nanostack_mac_tester/mbed_app.json

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{
2+
"macros": ["MBED_TRACE_LINE_LENGTH=200", "OS_TASKCNT=4", "OS_IDLESTKSIZE=32"],
3+
"target_overrides": {
4+
"*": {
5+
"nanostack.configuration": "lowpan_host",
6+
"platform.stdio-convert-newlines": true,
7+
"platform.stdio-baud-rate": 115200,
8+
"mbed-mesh-api.heap-size": 6000,
9+
"nanostack-hal.event_loop_thread_stack_size": 2000,
10+
"mbed-trace.enable": true,
11+
"nsapi.default-stack": "LWIP",
12+
"target.device_has_add": ["802_15_4_PHY"],
13+
"atmel-rf.provide-default": true
14+
}
15+
}
16+
}

0 commit comments

Comments
 (0)