Network Terminal Example Summary

This example demonstrates the extensive networking capabilities of the CC35xx device.

Silo	Description
WLAN	Includes link layer functions such as scan, connect, etc.
Socket	Showcases a variety of socket APIs responsible for sending and receiving data.
BLE	Provides basic BLE commands.

Each silo contains several commands accessible via the command line interface, implemented using the user UART. Any events or application output will be displayed on the UART terminal screen. In the Available Commands section, we will discuss each silo and its commands in greater detail.

Example Usage

Build the project and run it. See the Getting Started Guide in the docs directory of your SDK root.
Open a serial port session (e.g., ‘HyperTerminal’, ‘puTTY’, ‘Tera Term’, etc.) to the appropriate COM port, listed as ‘User UART’. The COM port can be determined via Device Manager in Windows or via ls /dev/tty* in Linux.

The connection should have the following settings:

    Baud-rate:    115200
    Data bits:    8
    Stop bits:    1
    Parity:       None
    Flow Control: None

Once the application completes its initialization and the network processor is up, the application banner will be displayed, showing version details:

******************************************************************
******************   Osprey Network Terminal   *******************
*******************      Version x.x.x.x      ********************
******************************************************************

At this point, a menu showing the available commands will be printed, followed by a command prompt, indicating that the application is ready for user input.

Application Overview

Network Terminal is a command-line interface (CLI) application used to demonstrate the networking capabilities of the CC35xx device. It offers a list of commands that are fed to the application via UART, then parsed and dispatched.

The application starts by invoking cmd_prompt(), which polls the UART input for a command. Polling is completed once a carriage return is detected. At this point, cmd_prompt possesses the command name, followed by the user’s choice of parameters. Once the command is obtained, cmd_prompt searches for the user’s command in the global command table, gCmdList. This table stores three entries for each command: the command string, a callback that handles the command, and a menu print callback that prints the help menu.

If the typed command matches a table entry, the handler is dispatched, and the parameters provided by the user are passed to the command callback. All callback functions follow the same naming convention: cmd<command_name>Callback and reside in the appropriate file. For example, all WLAN-related callbacks are implemented in wlan_cmd.c.

Inside each command callback, the first action is to parse the user’s input. This is achieved by calling the corresponding parser function. A structure containing each command’s parameters is also passed to the designated parser and returned filled with the parsed user’s parameters. Later, the parsed structure is handled by the callback. All command parser functions follow the same naming convention: Parse<command_name>Cmd. Parser functions reside in cmd_parser.c.

Once a dispatched callback finishes its run, the application returns to the cmd_prompt function, ready for another input from the user.

Available Commands

================================================================================
Available commands:

help                clear               wlan_ap_role_up     wlan_ap_role_down   
wlan_sta_role_up    wlan_sta_role_down  wlan_connect        wlan_disconnect     
wlan_scan           wlan_get_mac        wlan_set_mac        wlan_get_ps         
wlan_set_ps         wlan_set_pm         wlan_set_LSI        wlan_start          
wlan_stop           ble_adv_cfg         ble_adv_enable      ble_scan_cfg        
ble_scan_enable     ble_connect         ble_disconnect      ble_peers           
ble_start           ble_stop            ble_test_mode       calibrator          
send                recv                socket_show         kill                
================================================================================

wlan_start

This command turns on the WLAN device, initialize the upper MAC thread, and initialize the SPI interface.

Note: This command is called by the main function, and is used only if the user has called the wlan_stop command first.

wlan_stop

This command turns off the WLAN device and deactivates the SPI interface.

wlan_sta_role_up

This command adds and starts the station role on the device:

Adding a new STA netif interface to the network stack.
Adding a new WLAN role ID by dispatching CMD_ROLE_START to the CC35xx device.

Usage: 
        wlan_sta_role_up [-help] 

Description:
        Role up device as STA.

Note: This command is used to start the device in station mode after it is powered on and all modules are initialized.

wlan_sta_role_down

This command removes and finishes the station role on the device:

If the device is connected to an AP, disconnect it from the AP.
Remove the STA netif interface from the network stack.
Remove the STA WLAN role ID by dispatching CMD_ROLE_DISABLE to the CC35xx device.

wlan_scan

This command allows a user to retrieve scan results from the network processor.

Usage: 
  scan [-help] [-n <number of APs to display>]

  -n        Maximum number of scan results to show
  -help     Display this help.

Once the wlan_scan command has successfully completed, an event WLAN_EVENT_SCAN_RESULT will be triggered and the available devices will be printed to the UART console. Please refer to WlanEventHandler() implemented in network_terminal.c for more info.

Example:

scan -n 20

---------------------------------------------------------------------------------------------
    |               SSID               |       BSSID       | RSSI  | Ch | Hidden | Security |
---------------------------------------------------------------------------------------------
 1  | SSID1                            | 94:10:3e:c6:70:a4 | -26   | 1  | NO     | OPEN     |
 2  | SSID2                            | cc:db:93:43:da:80 | -61   | 1  | NO     | OPEN     |
 3  | SSID3                            | 34:03:de:10:fc:43 | -59   | 1  | NO     | WPA/WPA2 |
---------------------------------------------------------------------------------------------

Note: The maximum number to show is 20.

wlan_connect

This command allows a user to connect to an AP. It receives the following parameters:

SSID (Optional): The requested SSID of the AP. The application expects this parameter to be inside quotation marks (" “).
Security Type: The device supports four modes: [OPEN, WPA2, WPA3, WPS].
Password (Optional): The application expects this parameter to be inside quotation marks (" “).

When one of the [OPEN, WPA2, WPA3] Security Types is given, the connection is based on the SSID parameter, and hence this parameter is required. However, for [WPS], the SSID parameter is not allowed.

Usage: 
  wlan_connect [-help] [-s <"ssid name">] [-t <security type>] [-p <"password">]
    -s      SSID
    -t      Type of security (security type = [OPEN, WPA/WPA2])
    -p      Password in ASCII characters

Note: This command is blocking, and the timeout is configured by WLAN_EVENT_TOUT in wlan_cmd.c. For WPS, the timeout is two minutes.

Expected Host Events - During the connection process to an AP, some async events are expected from the device side. These include:

WLAN_EVENT_CONNECT: This event signals that the device is connected to an AP. It also prints details about the connected AP, such as SSID and BSSID. Please refer to WlanEventHandler() implemented in network_terminal.c for more info.
WLAN_EVENT_DISCONNECT: If the device is already connected to an AP, it will disconnect from the old one before attempting to connect to the requested AP. The disconnect reason code will be: WLAN_DISCONNECT_USER_INITIATED. Please refer to WlanEventHandler() implemented in network_terminal.c for more info.

Example:

wlan_connect -s "myhome network" -t WPA2 -p "password"

wlan_disconnect

This command allows a user to disconnect from an AP, if currently connected to one.

Expected Host Events:
WLAN_EVENT_DISCONNECT: This event also prints details about the disconnected AP, such as SSID and BSSID. Refer to WlanEventHandler() implemented in network_terminal.c for more info.

wlan_get_mac

This command allows a user to get the device MAC address. It receives the following parameter:

Role Type: There are two role types available: 0 for Station and 2 for Access Point (AP).

Usage: 
        wlan_get_mac [-help] [-i <RoleType>] 

Description:
        Get MacAddress. role type 0 - STA , 2 - AP 

        -i      RoleType, if role type does not exists error is return

        -help   Display this help

Note: We support STA role, AP role, and Multi role.

Example:

wlan_get_mac -i 0

[MAC ADDRESS] : a8:1b:6a:a9:90:f2

wlan_set_mac

This command allows a user to set the device’s MAC address. It receives the following parameters:

Role Type: There are two role types available: 0 for Station and 2 for Access Point (AP).
MAC Address: The new MAC address.

Usage: 
        wlan_set_mac [-help] [-i <RoleType>] [-m <macAdress>]

Description:
        Set MacAddress. Role type 0 - STA, 2 - AP 

        -i      RoleType, if role type does not exist, an error is returned

        -m      MacAddress, if MAC address is not valid, an error is returned

        -help   Display this help

To apply the changes, you must run wlan_sta_role_down and then wlan_sta_role_up.

Example:

wlan_set_mac -i 0 -m AA:BB:CC:DD:EE:FF

wlan_sta_role_down

wlan_sta_role_up

wlan_get_mac -i 0

[MAC ADDRESS] : aa:bb:cc:dd:ee:ff

wlan_get_ps

This command allows a user to get the current power save mode.

Usage: 
        wlan_get_ps [-help] 
Description:
        Get current power save mode. 0 - Auto PS , 1 - Active mode, 2 - power save mode

Note: The device starts in Active mode.

wlan_set_ps

This command allows a user to set the device’s power save mode. It receives the following parameter:

Power Save Mode: There are three modes available: 0 for Auto PS, 1 for Active mode, and 2 for Power Save mode.

Usage:
        wlan_set_ps [-help] [-m <PowerSaveMode>]

Description:
        Set power save mode. 0 - Auto PS , 1 - Active mode, 2 - power save mode

        -m      Mode, if device not started error is return

        -help   Display this help

Socket Commands

send
recv
socket_show
kill

send

This command demonstrates sending data in packets using the networking API. It allows a user to open UDP or TCP client sockets and send packets in various configurations. It receives the following parameters:

Protocol: TCP/UDP
Port Number
Blocking vs. Non-blocking option
Number of packets to transmit. Setting this to 0 will send infinite packets

Usage:
        send [-help] [-c <server ip address>] [-u] [-p <port number>]  [-nb] [-n <number of packets>]  
        
        -c      Run in client mode and connect to mentioned server - IP should be in '.' format 
        -u      Use UDP rather than TCP
        -p      Port number to send/receive data (Default is 5001)
        -nb     Create non-blocking socket rather than blocking
        -n      Number of packets to transmit (Default is 1000)
        -V      Use IPv6 rather than IPv4

Once all packets have been sent or the timeout has expired (see RECEIVE_TIMEOUT in network_terminal.h), the application will return to the main menu.

Example:

send -c 10.0.0.10 -u -p 5001 -n 1500

Infinity option - Setting the number of packets to 0:

This option will initiate a new task.
The task will continuously send packets in an infinite loop.
For more details on managing this option, refer to the kill and socket_show commands.

recv

This command demonstrates the reception of data in packets using the networking API.

This command allows a user to open UDP or TCP server sockets and receive packets in various configurations. It receives the following parameters:

Protocol: TCP/UDP
Port Number
Blocking vs. Non-blocking option
Number of packets to transmit. Setting this to 0 will receive infinite packets

Usage:
        recv [-help] [-u] [-p <port number>] [-nb] [-n <number of packets>]          

        -u      Use UDP rather than TCP
        -p      Port number to send/receive data (Default is 5001)
        -nb     Create non-blocking socket rather than blocking
        -n      Number of packets to transmit (Default is 1000)
        -V      Use IPv6 rather than IPv4

Once all packets have been received or the timeout has expired (refer to RECEIVE_TIMEOUT in network_terminal.h), the application will return to the main menu.

Example:

recv -u -p 5001 -n 1500

Infinity option - Setting the number of packets to 0:

This option will initiate a new task.
The task will continuously receive packets in an infinite loop.
For more details on managing this option, refer to the kill and socket_show commands.

socket_show

This command allows the user to display the currently running socket processes.

Each process has a unique ID and a descriptive name.

Example:
socket_show 

         Process running: 

        ---id 0          UDP client
        ---id 1          UDP server

kill

This command allows a user to close specific running socket processes by their ID.

Usage:
        kill [-help] [-i <id>]

Description:
        kill available running process by id

Example:

kill -i 0
kill -i 1

BLE commands

ble_start
ble_stop
ble_adv_cfg
ble_adv_enable
ble_scan_cfg
ble_scan_enable
ble_connect
ble_disconnect
ble_peers
ble_test_mode

ble_start

This command turns on the BLE controller and host, and initializes the BLE interface.

ble_stop

This command stops the BLE controller and host.

ble_adv_cfg

This command configures the BLE advertising instance. It receives the following parameters:

Advertising interval
Type (legacy or extended)
Primary PHY settings
Secondary PHY settings
Instance ID

Usage:
        ble_adv_cfg [-i <instance>] [-l <legacy [0:extended/1:legacy]>] [-n <interval (ms)>] [-p <primary phy [1:1M/2:2M/3:coded]>] [-s <secondary phy [1:1M/2:2M/3:coded]>]

Description:
        Configure a specific advertise instance.
        Can be used with no parameters.
        Default Parameters: instance 0, extended, 100ms interval, 1M PHY    

Example:
        ble_adv_cfg
        ble_adv_cfg -i 0 -l 0 -n 100 -p 1 -s 1

ble_adv_enable

This command enables or disables a BLE advertising instance. It receives the following parameters:

Enable or disable the advertising instance.
Specify the advertising instance to be configured.
Set the duration for the advertising in units of 10 milliseconds.
Set the maximum number of advertising events.

Usage:
        ble_adv_enable [-e <enable [0/1]>] [-i <instance>] [-d <duration (10ms units)>] [-m <max events]

Description:
        Enable or disable a specific advertise instance.
        Can be called only after a previous ble_adv_cfg command.
        Can be used with no parameters.
        Default Parameters: enable with no expiration and max events 0  

Example:
        ble_adv_enable
        ble_adv_enable -e 1 -i 0 -d 0 -m 0
        ble_adv_enable -e 0 -i 0

ble_scan_cfg

This command sets the BLE scan configuration. It receives the following parameters:

Scan interval in milliseconds.
Scan window in milliseconds.
PHY (physical layer) settings.

Usage:
        ble_scan_cfg [-i <scan interval (ms)>] [-w <scan window (ms)>] [-p <phy [ 1:1M/4:coded/5:mixed]>]

Description:
        Configure BLE scan
        Can be used with no parameters.
        Default Parameters: Default Parameters: extended 1M PHY, scan interval of 100ms and scan window of 50ms

Example:
        ble_scan_cfg
        ble_scan_cfg -i 100 -w 50 -p 1

ble_scan_enable

This command enables or disables BLE scanning. It receives the following parameters:

Enable or disable the scanning.
Filter duplicates option.
Scan period in seconds.

Usage:
        ble_scan_enable [-e <enable [0/1]>] [-f <filter duplicate [0/1/2]>] [-p <period (sec)>]

Description:
        Enable or disable Ble scan.
        Can be called only after a previous ble_scan_cfg command.
        Can be used with no parameters.
        Default Parameters: enable with scan duration of 3s, scan period 0s and no filter duplicate

Example:
        ble_scan_enable
        ble_scan_enable -e 1 -f 0 -p 0
        ble_scan_enable -e 0
        
--------------------------------------------------------------
| ID |        NAME      |    PEER ADDRESS   |  TYPE  |  RSSI |
--------------------------------------------------------------
| 0  | Simple Peripheal | A4:10:3E:C8:70:17 | PUBLIC |  -56  |
| 1  | Simple Central   | A4:2B:83:43:DA:90 | PUBLIC |  -70  | 
| 2  | Basic Peripheral | C0:03:DE:10:FC:43 | RANDOM |  -62  | 
--------------------------------------------------------------

ble_connect

This command allows a user to connect to a BLE peer device. It receives the following parameters:

Bluetooth Device Address: The address of the BLE device to connect to.
Address Type: The type of address used by the BLE device. Options are [PUBLIC, RANDOM].

Usage:
        ble_connect [-b <bd address>] [-t <address type [PUBLIC/RANDOM]

Description:
        Connect to a BLE peer device

Example:
        ble_connect -b A4:38:25:11:53:18 -t PUBLIC

ble_disconnect

This command allows a user to disconnect from a BLE peer device. It receives the following parameters:

Bluetooth Device Address: The address of the BLE device to disconnect from.
Address Type: The type of address used by the BLE device. Options are [PUBLIC, RANDOM].

Usage:
        ble_disconnect [-b <bd address>] [-t <address type [PUBLIC/RANDOM]

Description:
        Disconnect from a BLE peer device.
        Can be used with no parameters.
        Default action when no parameters is to disconnect all peers

Example:
        ble_disconnect
        ble_disconnect -b A4:38:25:11:53:18 -t PUBLIC

ble_peers

This command displays the list of all connected BLE peer devices.

Usage:
        ble_peers

Description:
        Display the list of all connected BLE peer devices with their attributes

Example:
        ble_peers
            
-------------------------------------------------------------
| Handle |   PEER ADDRESS    |  TYPE  |  OWN ROLE  | BONDED?|
-------------------------------------------------------------
| 0      | A4:10:3E:C8:70:17 | PUBLIC | PERIPHERAL | YES    |
| 1      | A4:2B:83:43:DA:90 | PUBLIC | CENTRAL    | NO     |
| 2      | C0:03:DE:10:FC:43 | RANDOM | PERIPHERAL | NO     |
-------------------------------------------------------------

ble_test_mode

This command sets the device into test mode (controller only mode). It receives the following parameter:

Enable or disable test mode.

Usage:
        ble_test_mode [-e <enable>]

Description:
        Enter into a controller only )no host) mode running over UART interface for testing purposes

Example:
        ble_test_mode -e 1
        ble_test_mode -e 0