Station API

Station API is used to work with ESP acting in station mode. It allows to join other access point, scan for available access points or simply disconnect from it.

An example below is showing how all examples (coming with this library) scan for access point and then try to connect to AP from list of preferred one.

Station manager used with all examples
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
#include "station_manager.h"
#include "lwesp/lwesp.h"

/*
 * List of preferred access points for ESP device
 * SSID and password
 *
 * ESP will try to scan for access points
 * and then compare them with the one on the list below
 */
ap_entry_t
ap_list[] = {
    //{ "SSID name", "SSID password" },
    { "TilenM_ST", "its private" },
    { "Majerle WIFI", "majerle_internet_private" },
    { "Majerle AMIS", "majerle_internet_private" },
};

/**
 * \brief           List of access points found by ESP device
 */
static
lwesp_ap_t aps[100];

/**
 * \brief           Number of valid access points in \ref aps array
 */
static
size_t apf;

/**
 * \brief           Connect to preferred access point
 *
 * \note            List of access points should be set by user in \ref ap_list structure
 * \param[in]       unlimited: When set to 1, function will block until SSID is found and connected
 * \return          \ref lwespOK on success, member of \ref lwespr_t enumeration otherwise
 */
lwespr_t
connect_to_preferred_access_point(uint8_t unlimited) {
    lwespr_t eres;
    uint8_t tried;

    /*
     * Scan for network access points
     * In case we have access point,
     * try to connect to known AP
     */
    do {
        if (lwesp_sta_has_ip()) {
            return lwespOK;
        }

        /* Scan for access points visible to ESP device */
        printf("Scanning access points...\r\n");
        if ((eres = lwesp_sta_list_ap(NULL, aps, LWESP_ARRAYSIZE(aps), &apf, NULL, NULL, 1)) == lwespOK) {
            tried = 0;
            /* Print all access points found by ESP */
            for (size_t i = 0; i < apf; i++) {
                printf("AP found: %s, CH: %d, RSSI: %d\r\n", aps[i].ssid, aps[i].ch, aps[i].rssi);
            }

            /* Process array of preferred access points with array of found points */
            for (size_t j = 0; j < LWESP_ARRAYSIZE(ap_list); j++) {
                for (size_t i = 0; i < apf; i++) {
                    if (!strcmp(aps[i].ssid, ap_list[j].ssid)) {
                        tried = 1;
                        printf("Connecting to \"%s\" network...\r\n", ap_list[j].ssid);
                        /* Try to join to access point */
                        if ((eres = lwesp_sta_join(ap_list[j].ssid, ap_list[j].pass, NULL, NULL, NULL, 1)) == lwespOK) {
                            lwesp_ip_t ip;
                            uint8_t is_dhcp;
                            lwesp_sta_copy_ip(&ip, NULL, NULL, &is_dhcp);

                            printf("Connected to %s network!\r\n", ap_list[j].ssid);
                            printf("Station IP address: %d.%d.%d.%d; Is DHCP: %d\r\n",
                                   (int)ip.ip[0], (int)ip.ip[1], (int)ip.ip[2], (int)ip.ip[3], (int)is_dhcp);
                            return lwespOK;
                        } else {
                            printf("Connection error: %d\r\n", (int)eres);
                        }
                    }
                }
            }
            if (!tried) {
                printf("No access points available with preferred SSID!\r\nPlease check station_manager.c file and edit preferred SSID access points!\r\n");
            }
        } else if (eres == lwespERRNODEVICE) {
            printf("Device is not present!\r\n");
            break;
        } else {
            printf("Error on WIFI scan procedure!\r\n");
        }
        if (!unlimited) {
            break;
        }
    } while (1);
    return lwespERR;
}
group LWESP_STA

Station API.

Functions

lwespr_t lwesp_sta_join(const char *name, const char *pass, const lwesp_mac_t *mac, const lwesp_api_cmd_evt_fn evt_fn, void *const evt_arg, const uint32_t blocking)

Join as station to access point.

Configuration changes will be saved in the NVS area of ESP device.

Return

lwespOK on success, member of lwespr_t enumeration otherwise

Parameters

  • [in] name: SSID of access point to connect to

  • [in] pass: Password of access point. Use NULL if AP does not have password

  • [in] mac: Pointer to MAC address of AP. If multiple APs with same name exist, MAC may help to select proper one. Set to NULL if not needed

  • [in] evt_fn: Callback function called when command has finished. Set to NULL when not used

  • [in] evt_arg: Custom argument for event callback function

  • [in] blocking: Status whether command should be blocking or not

lwespr_t lwesp_sta_quit(const lwesp_api_cmd_evt_fn evt_fn, void *const evt_arg, const uint32_t blocking)

Quit (disconnect) from access point.

Return

lwespOK on success, member of lwespr_t enumeration otherwise

Parameters

  • [in] evt_fn: Callback function called when command has finished. Set to NULL when not used

  • [in] evt_arg: Custom argument for event callback function

  • [in] blocking: Status whether command should be blocking or not

lwespr_t lwesp_sta_autojoin(uint8_t en, const lwesp_api_cmd_evt_fn evt_fn, void *const evt_arg, const uint32_t blocking)

Configure auto join to access point on startup.

Note

For auto join feature, you need to do a join to access point with default mode. Check lwesp_sta_join for more information

Return

lwespOK on success, member of lwespr_t enumeration otherwise

Parameters

  • [in] en: Set to 1 to enable or 0 to disable

  • [in] evt_fn: Callback function called when command has finished. Set to NULL when not used

  • [in] evt_arg: Custom argument for event callback function

  • [in] blocking: Status whether command should be blocking or not

lwespr_t lwesp_sta_reconnect_set_config(uint16_t interval, uint16_t rep_cnt, const lwesp_api_cmd_evt_fn evt_fn, void *const evt_arg, const uint32_t blocking)

Set reconnect interval and maximum tries when connection drops.

Return

lwespOK on success, member of lwespr_t enumeration otherwise

Parameters

  • [in] interval: Interval in units of seconds. Valid numbers are 1-7200 or 0 to disable reconnect feature

  • [in] rep_cnt: Repeat counter. Number of maximum tries for reconnect. Valid entries are 1-1000 or 0 to always try. This parameter is only valid if interval is not 0

lwespr_t lwesp_sta_getip(lwesp_ip_t *ip, lwesp_ip_t *gw, lwesp_ip_t *nm, const lwesp_api_cmd_evt_fn evt_fn, void *const evt_arg, const uint32_t blocking)

Get station IP address.

Return

lwespOK on success, member of lwespr_t enumeration otherwise

Parameters

  • [out] ip: Pointer to variable to save IP address

  • [out] gw: Pointer to output variable to save gateway address

  • [out] nm: Pointer to output variable to save netmask address

  • [in] evt_fn: Callback function called when command has finished. Set to NULL when not used

  • [in] evt_arg: Custom argument for event callback function

  • [in] blocking: Status whether command should be blocking or not

lwespr_t lwesp_sta_setip(const lwesp_ip_t *ip, const lwesp_ip_t *gw, const lwesp_ip_t *nm, const lwesp_api_cmd_evt_fn evt_fn, void *const evt_arg, const uint32_t blocking)

Set station IP address.

Application may manually set IP address. When this happens, stack will check for DHCP settings and will read actual IP address from device. Once procedure is finished, LWESP_EVT_WIFI_IP_ACQUIRED event will be sent to application where user may read the actual new IP and DHCP settings.

Configuration changes will be saved in the NVS area of ESP device.

Note

DHCP is automatically disabled when using static IP address

Return

lwespOK on success, member of lwespr_t enumeration otherwise

Parameters

  • [in] ip: Pointer to IP address

  • [in] gw: Pointer to gateway address. Set to NULL to use default gateway

  • [in] nm: Pointer to netmask address. Set to NULL to use default netmask

  • [in] evt_fn: Callback function called when command has finished. Set to NULL when not used

  • [in] evt_arg: Custom argument for event callback function

  • [in] blocking: Status whether command should be blocking or not

lwespr_t lwesp_sta_getmac(lwesp_mac_t *mac, const lwesp_api_cmd_evt_fn evt_fn, void *const evt_arg, const uint32_t blocking)

Get station MAC address.

Return

lwespOK on success, member of lwespr_t enumeration otherwise

Parameters

  • [out] mac: Pointer to output variable to save MAC address

  • [in] evt_fn: Callback function called when command has finished. Set to NULL when not used

  • [in] evt_arg: Custom argument for event callback function

  • [in] blocking: Status whether command should be blocking or not

lwespr_t lwesp_sta_setmac(const lwesp_mac_t *mac, const lwesp_api_cmd_evt_fn evt_fn, void *const evt_arg, const uint32_t blocking)

Set station MAC address.

Configuration changes will be saved in the NVS area of ESP device.

Return

lwespOK on success, member of lwespr_t enumeration otherwise

Parameters

  • [in] mac: Pointer to variable with MAC address

  • [in] evt_fn: Callback function called when command has finished. Set to NULL when not used

  • [in] evt_arg: Custom argument for event callback function

  • [in] blocking: Status whether command should be blocking or not

uint8_t lwesp_sta_has_ip(void)

Check if ESP got IP from access point.

Return

1 on success, 0 otherwise

uint8_t lwesp_sta_is_joined(void)

Check if station is connected to WiFi network.

Return

1 on success, 0 otherwise

lwespr_t lwesp_sta_copy_ip(lwesp_ip_t *ip, lwesp_ip_t *gw, lwesp_ip_t *nm, uint8_t *is_dhcp)

Copy IP address from internal value to user variable.

Note

Use lwesp_sta_getip to refresh actual IP value from device

Return

lwespOK on success, member of lwespr_t enumeration otherwise

Parameters

  • [out] ip: Pointer to output IP variable. Set to NULL if not interested in IP address

  • [out] gw: Pointer to output gateway variable. Set to NULL if not interested in gateway address

  • [out] nm: Pointer to output netmask variable. Set to NULL if not interested in netmask address

  • [out] is_dhcp: Pointer to output DHCP status variable. Set to NULL if not interested

lwespr_t lwesp_sta_list_ap(const char *ssid, lwesp_ap_t *aps, size_t apsl, size_t *apf, const lwesp_api_cmd_evt_fn evt_fn, void *const evt_arg, const uint32_t blocking)

List for available access points ESP can connect to.

Return

lwespOK on success, member of lwespr_t enumeration otherwise

Parameters

  • [in] ssid: Optional SSID name to search for. Set to NULL to disable filter

  • [in] aps: Pointer to array of available access point parameters

  • [in] apsl: Length of aps array

  • [out] apf: Pointer to output variable to save number of access points found

  • [in] evt_fn: Callback function called when command has finished. Set to NULL when not used

  • [in] evt_arg: Custom argument for event callback function

  • [in] blocking: Status whether command should be blocking or not

lwespr_t lwesp_sta_get_ap_info(lwesp_sta_info_ap_t *info, const lwesp_api_cmd_evt_fn evt_fn, void *const evt_arg, const uint32_t blocking)

Get current access point information (name, mac, channel, rssi)

Note

Access point station is currently connected to

Return

lwespOK on success, member of lwespr_t enumeration otherwise

Parameters

  • [in] info: Pointer to connected access point information

  • [in] evt_fn: Callback function called when command has finished. Set to NULL when not used

  • [in] evt_arg: Custom argument for event callback function

  • [in] blocking: Status whether command should be blocking or not

uint8_t lwesp_sta_is_ap_802_11b(lwesp_ap_t *ap)

Check if access point is 802.11b compatible.

Return

1 on success, 0 otherwise

Parameters

uint8_t lwesp_sta_is_ap_802_11g(lwesp_ap_t *ap)

Check if access point is 802.11g compatible.

Return

1 on success, 0 otherwise

Parameters

uint8_t lwesp_sta_is_ap_802_11n(lwesp_ap_t *ap)

Check if access point is 802.11n compatible.

Return

1 on success, 0 otherwise

Parameters

struct lwesp_sta_t
#include <lwesp_typedefs.h>

Station data structure.

Public Members

lwesp_ip_t ip

IP address of connected station

lwesp_mac_t mac

MAC address of connected station