homechevron_rightDocschevron_rightGuides & Tutorialschevron_rightNotecard Guideschevron_rightConnecting to a WiFi Access Point

Connecting to a WiFi Access Point

The Notecard WiFi and Notecard Cell+WiFi have the ability to connect to WiFi access points and transmit data over WiFi networks. In this guide you'll learn two different ways to set up a connection.

note

To connect a Notecard WiFi to a WiFi access point, you must first connect the Notecard to a companion Notecarrier board. If you're not sure how to do so, refer to our guide on connecting a Notecard to a Notecarrier.

Once you have your Notecard seated on a Notecarrier, you're ready to connect it to a local WiFi access point. There are two ways to accomplish this:

  1. Using a Notecard API Command
  2. Using Your Smartphone
warning

Before you continue, please note that Notecard WiFi and Notecard Cell+WiFi are only compatible with 2.4 GHz WiFi access points. Access points that combine 5 GHz and 2.4 GHz with the same SSID may cause issues using the Notecard. Also, ensure your Notecard firmware version is at least v3.3.1. Specifying multiple access points requires v7.5.2 or later.

note

On Notecard Cell+WiFi, WiFi is used automatically once credentials are configured. The default card.transport method is "wifi-cell", which prefers WiFi and falls back to cellular when a WiFi connection can't be established. If no WiFi credentials are configured, Notecard skips WiFi entirely and uses cellular.

Using a Notecard API Command

Connect your Notecarrier to your computer via USB. You should see a red LED flash repeatedly, letting you know it's booting up. Using your terminal program (or the In-Browser Terminal), send this request to your Notecard:

{"req":"card.wifi","ssid":"<ssid name>","password":"<password>"}

In return, you'll get a confirmation that your Notecard is set to connect to the specified SSID using a specific security protocol. For example:

{
  "secure": true,
  "version": "3.12.3",
  "ssid": "<ssid name>",
  "security": "wpa2-psk"
}

WiFi credentials set via card.wifi are saved to non-volatile flash storage on the Notecard and persist across power cycles and reboots. You can read back the currently configured SSID at any time by sending {"req":"card.wifi"} with no other arguments.

note
  • To connect to an open access point that has no password, pass "password":"-".
  • WiFi credentials cannot be changed while Notecard is in continuous mode, because a new session is required to apply them. If your Notecard is in continuous mode, first switch it to periodic or off with a hub.set request, then send card.wifi.

Follow the instructions provided below to validate your WiFi connection.

Using Your Smartphone

Alternatively, you can set up your Notecard WiFi using your smartphone.

With your Notecard and Notecarrier plugged into a power supply, locate the AP button on your Notecard (see images below). Press and hold the button for about three seconds, and then release. The Notecard's red LED turns on while it's in SoftAP mode.

note

You can also enter SoftAP mode without pressing the button by sending {"req":"card.wifi","start":true}. Either way, SoftAP mode shuts itself down after five minutes if you don't complete the configuration, and you can cancel it early by double-pressing the AP button. While SoftAP mode is active, Notecard rejects most other API requests with a {softap} error.

Notecard WiFi v1Notecard WiFi v2
The location of the black button on v1The location of the black button on v2
Notecard Cell+WiFi
The location of the button on a Cell+WiFi Notecard

Next, open up your smartphone and browse for available WiFi access points. Within a minute or so, you should see "Notecard" as an option. (The name of this access point is configurable with the card.wifi request's name argument, so it may differ if your Notecard has been customized.)

A list of available access points on a smartphone

Connect to "Notecard" on your phone and you'll be redirected to a window where you can enter the SSID and password. You can also use the "Scan networks" button to look for available access points, then tap on an access point to fill the SSID.

note

If the browser window doesn't automatically appear after connecting to the Notecard SSID, enter the following IP address in your phone's web browser:

  • Notecard WiFi v1, Notecard Cell+WiFi: 10.10.0.1
  • Notecard WiFi v2: 10.0.0.1

The Notecard WiFi's connection screen

Tap "Connect" to complete your WiFi configuration. Your Notecard should reboot (note the flashing red LEDs), at which point you'll have successfully connected.

Finally, follow the instructions provided below to validate your WiFi connection.

Validating Your WiFi Connection

You'll know that your Notecard's WiFi connection is active when the green LED (Notecard WiFi v1) is on, or the red LED (Notecard WiFi v2, Notecard Cell+WiFi) blinks. Don't worry if it's not lit right now, as the WiFi radio only turns on after you make your first hub.set request and sync with Notehub via a hub.sync request. If you're unsure how to send these commands, refer to the Notecard quickstart.

As of Notecard firmware v3.3.1, you can also issue a card.wireless request to verify the SSID, IP address of the Notecard, and the IP address of the gateway. For example:

> 
{"req":"card.wireless"}
{
 "status": "{network-up}",
 "mode": "auto",
 "count": 5,
 "net": {
  "imei": "89:DE:E5:11:XX:00",
  "ssid": "<ssid name>",
  "bssid": "A6:12:35:ED:F0:10",
  "rat": "wifi-2.4",
  "rssi": -32,
  "bars": 5,
  "ip": "192.168.0.200",
  "gateway": "192.168.0.1",
  "cid": 9,
  "updated": 1669834743
 }
}

The LED is lit only while the WiFi connection is active. If you set the Notecard's mode to "continuous", the Notecard will maintain a connection to your access point. If you set the Notecard's mode to "periodic", the Notecard will only connect when it needs to transfer data.

If you change your WiFi configuration and the hub.sync.status command returns "status": "connect delayed...", power cycle the Notecard to have it immediately use the new WiFi configuration.

Notecard WiFi v1Notecard WiFi v2
The green LED on a Notecard WiFi v1The red LED on a Notecard WiFi v2
Notecard Cell+WiFi
The red LED on a Notecard Cell+WiFi

Specifying Multiple Access Points

As of Notecard firmware v7.5.2, you can specify multiple WiFi access points for a Notecard to attempt to use. The sections below detail the two ways you can do this: the text argument in a card.wifi request, and the reserved _wifi environment variable.

Providing Access Points Through the card.wifi Request

If your Notecard will only ever use one WiFi network, you can use the card.wifi request's ssid and password arguments as covered in an earlier section.

{"req":"card.wifi","ssid":"your-ssid","password":"your-password"}

However, if your Notecard needs the ability to connect to multiple networks at different times (for example a device that moves between two buildings), you can use the card.wifi request's text argument. The text argument takes a string in the following format:

["FIRST-SSID","FIRST-PASSWORD"],["SECOND-SSID","SECOND-PASSWORD"]

When passing this string to a Notecard you may need to escape the quotes within the string. For example, the following is a valid request that specifies two access points to pass to a Notecard through the In-Browser Terminal.

{"req":"card.wifi", "text":"[\"FIRST-SSID\",\"FIRST-PASSWORD\"],[\"SECOND-SSID\",\"SECOND-PASSWORD\"]"}
note
  • To include an open access point that has no password, provide only the SSID, for example ["OPEN-SSID"].
  • The text list is stored separately from the ssid and password arguments. Setting text does not clear a network previously configured with ssid and password, and vice versa. Notecard tries both when connecting.

Providing Access Points Through the _wifi Environment Variable

You can also pass a list of WiFi access points for a Notecard to use through the _wifi reserved environment variable. The environment variable takes the same format as the card.wifi request's text argument:

["FIRST-SSID","FIRST-PASSWORD"],["SECOND-SSID","SECOND-PASSWORD"]

The advantage of using the environment variable approach is it gives you the ability to remotely change your Notecard's network configuration. Because environment variables are delivered from Notehub, Notecard must first connect (over a previously configured WiFi network, or over cellular on Notecard Cell+WiFi) to receive the _wifi value. For a complete walkthrough, see the Managing a Notecard's WiFi Network Remotely sample app.

How a Notecard Selects an Access Point

When you provide a Notecard multiple access points (through any of the methods above), the Notecard does the following to select an access point to use:

  • If the _wifi environment variable is set, it replaces any list provided through the card.wifi request's text argument; the two lists are not merged. A network configured with the card.wifi request's ssid and password arguments remains a candidate either way.

  • The Notecard performs a WiFi scan for all SSIDs it has credentials for, and attempts to connect to them in order of strongest RSSI (signal strength).

  • After a successful connection, the WiFi SSID, password, and security mode that were used are cached in RAM, and subsequent connections will attempt to use this connection first.

Common Connection Failure Issues

There are a variety of reasons why a Notecard may be unable to connect to a WiFi access point (SSID). One of the following error messages may be returned when a Notecard is unable to connect.

note

These messages appear in the status field of a hub.sync.status response after Notecard attempts to connect, and in the device's session log in Notehub. Each message includes one or more bracketed error codes, such as {wifi-auth} or {wifi-config}, which are described in Notecard Error and Status Codes.

  • authentication failure - The provided password is incorrect.
  • invalid parameter - The password is too short or the SSID is too long.
  • AP not found - The SSID is incorrect, out of range, or no password was supplied.
  • connection timeout - The Notecard found the access point but the connection attempt timed out before completing (for example, a weak signal or an unresponsive access point).
  • connection rejected - The access point actively refused the connection (for example, MAC-address filtering or a limit on the number of connected clients).
  • connection aborted - The access point dropped the connection before it completed.
  • wifi: Couldn't connect to any configured ssid {wifi-config} - Notecard tried every set of credentials it has and none succeeded. Check the SSID and password, and confirm the access point is 2.4 GHz.

After several consecutive failed connection attempts, Notecard appends {extended-network-failure} to the error and backs off before retrying. See Checking Penalty Box Status for how to tell whether Notecard is currently waiting before its next attempt.