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 "esp/esp.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
esp_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 espOK on success, member of \ref espr_t enumeration otherwise
 */
espr_t
connect_to_preferred_access_point(uint8_t unlimited) {
    espr_t eres;
    uint8_t tried;

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

        /* Scan for access points visible to ESP device */
        printf("Scanning access points...\r\n");
        if ((eres = esp_sta_list_ap(NULL, aps, ESP_ARRAYSIZE(aps), &apf, NULL, NULL, 1)) == espOK) {
            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 < ESP_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 = esp_sta_join(ap_list[j].ssid, ap_list[j].pass, NULL, NULL, NULL, 1)) == espOK) {
                            esp_ip_t ip;
                            uint8_t is_dhcp;
                            esp_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 espOK;
                        } 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 == espERRNODEVICE) {
            printf("Device is not present!\r\n");
            break;
        } else {
            printf("Error on WIFI scan procedure!\r\n");
        }
        if (!unlimited) {
            break;
        }
    } while (1);
    return espERR;
}
group ESP_STA

Station API.

Functions

espr_t esp_sta_join(const char *name, const char *pass, const esp_mac_t *mac, const esp_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

espOK on success, member of espr_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

espr_t esp_sta_quit(const esp_api_cmd_evt_fn evt_fn, void *const evt_arg, const uint32_t blocking)

Quit (disconnect) from access point.

Return

espOK on success, member of espr_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

espr_t esp_sta_autojoin(uint8_t en, const esp_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 esp_sta_join for more information

Return

espOK on success, member of espr_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

espr_t esp_sta_getip(esp_ip_t *ip, esp_ip_t *gw, esp_ip_t *nm, const esp_api_cmd_evt_fn evt_fn, void *const evt_arg, const uint32_t blocking)

Get station IP address.

Return

espOK on success, member of espr_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

espr_t esp_sta_setip(const esp_ip_t *ip, const esp_ip_t *gw, const esp_ip_t *nm, const esp_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, ESP_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

espOK on success, member of espr_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

espr_t esp_sta_getmac(esp_mac_t *mac, const esp_api_cmd_evt_fn evt_fn, void *const evt_arg, const uint32_t blocking)

Get station MAC address.

Return

espOK on success, member of espr_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

espr_t esp_sta_setmac(const esp_mac_t *mac, const esp_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

espOK on success, member of espr_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 esp_sta_has_ip(void)

Check if ESP got IP from access point.

Return

1 on success, 0 otherwise

uint8_t esp_sta_is_joined(void)

Check if station is connected to WiFi network.

Return

1 on success, 0 otherwise

espr_t esp_sta_copy_ip(esp_ip_t *ip, esp_ip_t *gw, esp_ip_t *nm, uint8_t *is_dhcp)

Copy IP address from internal value to user variable.

Note

Use esp_sta_getip to refresh actual IP value from device

Return

espOK on success, member of espr_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

espr_t esp_sta_list_ap(const char *ssid, esp_ap_t *aps, size_t apsl, size_t *apf, const esp_api_cmd_evt_fn evt_fn, void *const evt_arg, const uint32_t blocking)

List for available access points ESP can connect to.

Return

espOK on success, member of espr_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

espr_t esp_sta_get_ap_info(esp_sta_info_ap_t *info, const esp_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

espOK on success, member of espr_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 esp_sta_is_ap_802_11b(esp_ap_t *ap)

Check if access point is 802.11b compatible.

Return

1 on success, 0 otherwise

Parameters

uint8_t esp_sta_is_ap_802_11g(esp_ap_t *ap)

Check if access point is 802.11g compatible.

Return

1 on success, 0 otherwise

Parameters

uint8_t esp_sta_is_ap_802_11n(esp_ap_t *ap)

Check if access point is 802.11n compatible.

Return

1 on success, 0 otherwise

Parameters

struct esp_sta_t
#include <esp_typedefs.h>

Station data structure.

Public Members

esp_ip_t ip

IP address of connected station

esp_mac_t mac

MAC address of connected station