---
title: Connecting to a WiFi Access Point
description: Learn how to connect a Notecard WiFi to a WiFi Access Point
source_url: https://dev.blues.io/guides-and-tutorials/notecard-guides/connecting-to-a-wifi-access-point/
canonical_url: https://dev.blues.io/guides-and-tutorials/notecard-guides/connecting-to-a-wifi-access-point/
markdown_url: https://dev.blues.io/guides-and-tutorials/notecard-guides/connecting-to-a-wifi-access-point.md
---

# Connecting to a WiFi Access Point

The [Notecard WiFi](https://shop.blues.com/products/wifi-notecard?utm_source=dev-blues\&utm_medium=web\&utm_campaign=store-link) and [Notecard Cell+WiFi](https://shop.blues.com/products/notecard-cell-wifi?utm_source=dev-blues\&utm_medium=web\&utm_campaign=store-link) 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](https://shop.blues.com/collections/notecarrier?utm_source=dev-blues\&utm_medium=web\&utm_campaign=store-link). If you're not sure how to do so, refer to [our guide on connecting a Notecard to a Notecarrier](https://dev.blues.io/quickstart/notecard-quickstart.md).

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](#using-a-notecard-api-command)
2. [Using Your Smartphone](#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](https://dev.blues.io/notecard/notecard-firmware-releases.md).

## 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](https://dev.blues.io/terminal/)), send this request to your Notecard:

```json
{"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:

```json
{
  "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.

Follow the instructions provided below to [validate your WiFi connection](#validating-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 at least one full second, and then release.

| Notecard WiFi v1                                                                                                               | Notecard WiFi v2                                                                                                                  |
| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| ![The location of the black button on v1](https://dev.blues.io/images/guides/notecard-guides/wifi/black-button.jpg?v=200874cf) | ![The location of the black button on v2](https://dev.blues.io/images/guides/notecard-guides/wifi/black-button-v2.jpg?v=89b898d2) |

| Notecard Cell+WiFi                                                                                                                             |
| ---------------------------------------------------------------------------------------------------------------------------------------------- |
| ![The location of the button on a Cell+WiFi Notecard](https://dev.blues.io/images/guides/notecard-guides/wifi/cell-wifi-button.jpg?v=e92df1c8) |

Next, open up your smartphone and browse for available WiFi access points. Within a minute or so, you should see "Notecard" as an option:

![A list of available access points on a smartphone](https://dev.blues.io/images/guides/notecard-guides/wifi/access-points.png?v=e90ddb20)

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](https://dev.blues.io/images/guides/notecard-guides/wifi/connection-screen.jpg?v=8a3a7aa6)

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).

## Validating Your WiFi Connection

You'll know that your Notecard is **actively connected** to Notehub when the green LED (Notecard WiFi v1) or red LED (Notecard WiFi v2, Notecard Cell+WiFi) is on. Don't worry if it's not on right now, as it 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](https://dev.blues.io/quickstart/notecard-quickstart.md).

As of [Notecard firmware v3.3.1](https://dev.blues.io/notecard/notecard-firmware-releases.md#v3-3-1-may-23-2022), 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:

```json
{"req":"card.wireless"}
```

```json
{
 "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 remains on only when the connection to Notehub is active. If you set the [Notecard's `mode`](https://dev.blues.io/api-reference/notecard-api/hub-requests.md#hub-set) 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 v1                                                                                                        | Notecard WiFi v2                                                                                                         |
| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| ![The green LED on a Notecard WiFi v1](https://dev.blues.io/images/guides/notecard-guides/wifi/wifi-led.jpg?v=422fc687) | ![The red LED on a Notecard WiFi v2](https://dev.blues.io/images/guides/notecard-guides/wifi/wifi-led-v2.jpg?v=4d04e8bc) |

| Notecard Cell+WiFi                                                                                                           |
| ---------------------------------------------------------------------------------------------------------------------------- |
| ![The red LED on a Notecard Cell+WiFi](https://dev.blues.io/images/guides/notecard-guides/wifi/cell-wifi-led.jpg?v=e8064c89) |

## Specifying Multiple Access Points

As of [Notecard firmware v7.5.2](https://dev.blues.io/notecard/notecard-firmware-releases.md#v7-5-2-november-22-2024), 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.

```json
{"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:

```plaintext
["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](https://dev.blues.io/terminal/).

```json
{"req":"card.wifi", "text":"[\"FIRST-SSID\",\"FIRST-PASSWORD\"],[\"SECOND-SSID\",\"SECOND-PASSWORD\"]"}
```

### 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` [environment variable](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables.md). The environment variable takes the same format as the `card.wifi` request's `text` argument:

```plaintext
["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.

### 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 both the `_wifi` environment variable and the `card.wifi` request are used, the Notecard will attempt to use access points provided in the `_wifi` environment variable first.

- 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). As of Notecard firmware *v3.3.1*, one of the following error messages may be returned when a Notecard is unable to connect:

- `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).