DS_CAP_SYS_NETWORK

DS_CAP_SYS_NETWORK — Networking (Wi-Fi)

Description

This capability adds support for wireless networking. The following fields are implemented:

Field	Description	Default Value
const char *System::hostname	Hostname	espDS
const char *System::wifi_ssid	SSID of the network to connect to	(empty)
const char *System::wifi_pass	Password of the network to connect to	(empty)
const char* System::time_server	Time server to use for time synchronization	pool.ntp.org

Configuring hostname is not mandatory for networking to work, but you might want to alter it if you care how other devices in the network will see your ESP8266, or if you plan to use mDNS or Wi-Fi manager.

If Wi-Fi manager is enabled, the fields wifi_ssid and wifi_pass fields become unavailable. The field time_server is only available when time is enabled.

The capability implements the following methods:

  void System::connectNetwork(             // Connect to a known network
    JLed *led = nullptr                    // LED, if defined, can be used to signal connection progress
  );
  bool System::networkIsConnected();       // Return true if network connected
  String System::getNetworkName();         // Return network name
  String System::getNetworkDetails();      // Return network details
  String System::getLocalIPAddress();      // Return assigned IP address
  String System::getTimeServer();          // Return NTP server name (possibly, overridden via DHCP)

connectNetwork() will connect to a pre-configured network. This function is automatically called from System::begin(); you do not have to use it under normal circumstances. System LED, if enabled, will glow on startup while the network is being connected. Network connection timeout is 20 s. If connection was unsuccesful, LED will blink three times. Upon successful connection, LED is turned off and can be used for other tasks.

networkIsConnected() can be used to test if network is connected at a given moment of time.

getNetworkName() will return the name of the network. In absence of Wi-Fi manager, this name should normally match what's configured in the System::wifi_ssid field. When Wi-Fi manager is used, the network name will be fetched from credentials stored on flash.

getNetworkDetails() will give some additional information about network. In the case of Wi-Fi, this means Wi-Fi channel and AP signal strength:

Wi-Fi channel: 1, RSSI: -61 dBm

getLocalIPAddress() will return IP-address assigned by the network.

getTimeServer(), only available when time is enabled, will return the name of the time server used. Normally, it coincides with what's configured in time_server field, but, theoretically, it can be altered via DHCP (I never observed this in practice).

If you need to change the default time server, it can be done in two ways:

1. Set up a macro DS_TIME_SERVER in MySystem.h:

#define DS_TIME_SERVER "fr.pool.ntp.org"

2. Override System::time_server value in the sketch code:

const char *System::time_server = "fr.pool.ntp.org";

The first method is preferred; the second method may be removed in the future versions of the library (issue 65). If both methods are used at the same time, the second method will take precedence. Note that the value provided by either method is only used during controller startup (function System::begin()), so changing it later at runtime will have no effect. The initialization must be done in global area of a sketch or locally, but before calling System::begin()).

Requires

• ESP8266 Arduino Core — networking implementation

Cooperates With

• DS_CAP_SYS_LOG — if syslog is enabled, network connection process and result are reflected in syslog. The assigned IP address will be logged;
• DS_CAP_SYS_LED — if system LED is enabled, it will be used to indicate Wi-Fi connection process;
• DS_CAP_SYS_TIME — if time is enabled, it will be automatically synchronized via NTP;
• DS_CAP_WEBSERVER — if web server is enabled, its System Configuration page will include information on network name, details and received IP-address. If time is enabled, time server name will be equally included;
• DS_CAP_WIFIMANAGER — if Wi-Fi manager is enabled, on startup the network will connect using previously stored credentials, and Wi-Fi manager can be used to alter them.

Conflicts With

None.

Usage

MySystem.h:

#define DS_CAP_SYS_NETWORK  // Enable network

#include "System.h"         // System global definitions

sketch.ino:

#include "MySystem.h"

using namespace ds;

// Set network parameters
const char *System::wifi_ssid = "mySSID";             // Network SSID
const char *System::wifi_pass = "myPassword";         // Network password

void setup() {
     System::begin();
}

void loop() {
}

Mandatory Calls

System::begin()	Required
System::update()	Not required

Examples

• network
• wifimanager
• time_ntp

Bugs

• Network reconnection (e.g., if access point goes down) is not specifically monitored and will not be signalled with LED (issue #6);
• In ESP8266 several time servers could be configured, but getTimeServer() will return only the first one used;
• LED glowing during network connection appears jerky with the latest ESP8266 Arduino Core 3.0.0. It is believed to be a problem external to this library, as things do work with Core 2.7.4. If the issue does not go away with maintenance releases, it will have to be checked in more detail.

Availability

Version 1.0 or later. The macro DS_TIME_SERVER is available from version 1.2.

See Also

None.