Wireless for OPTA Quickstart

Introduction

This tutorial should take approximately 60–75 minutes to complete.

In this guide you'll learn how to use Blues Wireless for OPTA, an expansion module that can quickly add Cellular IoT connectivity to any OPTA PLC, including the Finder OPTA Codesys and the Arduino Opta family.

In this tutorial you'll learn how to assemble your hardware, how to configure your OPTA expansion, how to write firmware that communicates with the expansion module, and how to manage your data in the cloud.

Key Concepts to Know

Before you dive in, it's important to understand a few key concepts from the Blues ecosystem.

• The Notecard is a device-to-cloud data pump that reduces the complexity of building connected solutions with a secure, reliable cellular, WiFi, or LoRa connection. It's a System-on-Module (SOM) that's ready for embedding into any project. The Blues OPTA expansion uses a Notecard for connectivity.

• Notehub is the cloud service the Notecard uses to securely send and receive data. Notehub also provides a console for fleet management and secure connectors for routing data to 3rd-party cloud applications. You'll use Notehub throughout this tutorial to manage your device and data.

• A Note is a JSON object containing developer-provided content. A Note is the primary means of sending data to/from a Notecard.

Notecard and Notehub work together to provide bidirectional wireless communication capabilities, both outbound (from your OPTA PLC to the cloud), and inbound (from the cloud to your OPTA PLC). The full process makes seamless connectivity possible for the OPTA ecosystem.

Before You Begin

To complete this quickstart, make sure you have access to the following:

• The contents of a Blues Wireless for OPTA Bundle, which include:

  • Finder OPTA Codesys (type 8A.04.9.024.832C)

  • Blues Wireless for OPTA expansion module

  • Two LTE SMA antennas

• One of the following means of supplying power:

  • (Recommended) A bench power supply that can provide 12–24 volts, and appropriately rated jumper wires (typically 18AWG) to connect the voltage from the OPTA to the expansion module.

  • Two dedicated USB-C cables to independently power the OPTA and expansion module.

• A computer with an available USB port.

• A browser that supports the Web Serial API, like Chrome, Microsoft Edge, or Firefox.

• One of the following development environments, depending on how you'd like to program your OPTA (you'll choose in the Writing Firmware section):

  • CODESYS (Windows only) along with Finder's OPTA Configurator plug-in, both available from Finder's software page.

  • Arduino IDE 2.0+

• An internet connection that allows access to Notehub.

note

The Blues Wireless for OPTA also works with the Arduino Opta family (Opta Lite, Opta RS485, and Opta WiFi) and with Finder's Arduino-programmable OPTA models (types 8A.04.9.024.8300, 8310, and 8320). If you have one of those, follow the Arduino IDE instructions throughout this guide.

Connect Your Notecard

With introductions out of the way, let's get started!

In this section you'll connect to your Notecard, the module within the OPTA expansion that makes cellular connectivity possible, and run your first Notecard API request.

Connecting Antennas

The Notecard requires antennas to establish and maintain communication with cellular networks.

To attach antennas to your Notecard, start by locating the two SMA antennas that came in your Wireless for OPTA. Once you have them, attach each to the female SMA connectors to your OPTA expansion as shown in the image below.

Connect to the Notecard

With the antennas connected, you're ready to start communicating with the Notecard. To do so, connect a USB-C cable to the USB port on the bottom of your Blues OPTA expansion, as this connection will allow you to send serial requests to the Notecard.

With the USB-C cable connected, next locate the panel on the right-hand side of your browser window, which we call the In-Browser Terminal.

Within the In-Browser Terminal, click the USB Notecard button. A browser prompt will appear asking for permission to connect to a USB serial device:

• If you're on a Mac, select either Notecard (cu.usbmodemNOTE1) or Notecard (tty.usbmodemNOTE1).

• On Windows, the option will show up as USB Serial Device (COMx).

• On Linux the option will show up as Notecard (ttyACM0).

Validate Serial Connection

Now you're ready to send your first JSON request to the Notecard! All requests and responses to/from the Notecard are in JSON format and are structured with the command as the value of a req key. Additional arguments are written as additional key-value pairs. For example, {"req":"card.version"} or {"req":"hub.set", "mode":"continuous"}.

The first request you'll send invokes the card.version API, which returns metadata about your Notecard.

Copy and paste the following request into the In-Browser Terminal (click the TRY IT button below).

Hit Enter and you'll see a response similar to the example output.

{"req":"card.version"}

{
 "version": "notecard-11.3.1.17696",
 "device": "dev:860322068080248",
 "name": "Blues Wireless Notecard",
 "sku": "NOTE-WBNAW",
 "ordering_code": "FA0YT1N0ACAM",
 "board": "5.13",
 "wifi": true,
 "cell": true,
 "gps": true,
 "body": {
  "org": "Blues Wireless",
  "product": "Notecard",
  "target": "u5",
  "version": "notecard-u5-11.3.1",
  "ver_major": 11,
  "ver_minor": 3,
  "ver_patch": 1,
  "ver_build": 17696,
  "built": "Jun 11 2026 16:25:45"
 }
}

Well done! You have properly set up, configured, and validated your hardware. Next, you'll configure your Notecard to communicate with Notehub.

Set up Notehub

Notehub is a secure proxy cloud service that communicates with the Notecard, provides tooling for managing fleets of devices, allows you to perform over-the-air Notecard and host MCU firmware updates, and makes it easy for you to route data to your own cloud applications.

In this section, you'll set up a Notehub Project and create your first ProductUID. A ProductUID is the unique identifier you will use to associate a Notecard with a Notehub Project, and ensure that data from the Notecard ends up in the right location.

Create a Notehub Project

1. Sign in or sign up for Notehub using the links below.

   Create a Notehub Account

   Sign up

   Already have an account? Sign in

2. Click "Create Project" on the dashboard. In the New Project card, give your project a name and ProductUID.

   

   note

   The ProductUID must be globally unique. To reduce collisions, Notehub prepends a generated namespace based on your account email, for instance com.your-company.your-name:. Enter any identifier you like in the input on the right.

3. Take note of your ProductUID. This identifier is used by Notehub to associate your Notecard to your project.

   

Set Up Your Notecard

Now that you know how to send requests to the Notecard, let's next tell the Notecard about your Notehub project so it knows where to send data.

To associate the Notecard with your project in Notehub you must assign the ProductUID you created to your Notecard. A Notecard can easily be moved between projects over time, but it can only belong to one project at a time.

To set the ProductUID, you'll start by sending a hub.set JSON request to your Notecard. Once the Notecard has finished processing your request, it will send a JSON response back to your computer to let you know that the request is complete.

An empty JSON object ({}) from the Notecard indicates a successful request. If an error occurs, the Notecard will return a JSON object with an err key and a string describing the error that occurred.

Copy and paste the following Notecard request, making sure to replace com.your-company.your-name:your_product with the ProductUID you created in the last step (click the TRY IT button below).

{"req":"hub.set", "product":"com.your-company.your-name:your_product"}

{}

The JSON object above consists of two key-value pairs. The first provides the name of the request, denoted with the key req and a value of hub.set. The second, product, is one of the arguments for the hub.set request. You can see all the arguments for this and all Notecard requests in the API Documentation.

Validate Your ProductUID and Connection

In this section, you'll validate your Notecard configuration by performing a manual sync with Notehub and then request sync status updates from the Notecard.

Start a Sync

Initiate a synchronization between the Notecard and Notehub with a hub.sync request, as shown below.

{"req":"hub.sync"}

{}

Once a sync has started, you can monitor the state of the sync by watching the status bar at the top of the In-Browser Terminal.

As soon as you see "Successful Notehub sync [x]s ago", the sync is complete!

{"req":"hub.sync.status"}

{
  "status": "starting communications {wait-module} {connecting}",
  "requested": 2
}
...
{
  "status": "modem now ON {modem-on}",
  "requested": 6
}
...
{
  "status": "waiting for wireless service 6 sec [+---] {cell-registration-wait}",
  "requested": 12
}

{"req":"hub.sync.status"}

{
 "time": 1615585299,
 "completed": 4
}

You should now be able to return to Notehub, refresh the Devices page, and see that a device has been added to your project:

At this point it's worth taking a step back and thinking about what just happened here. Your device just connected to the cloud, over cellular, and you didn’t have to buy a SIM, sign up with a cellular provider, or manage a cellular modem. This is the magic of the Notecard—cellular just works!

Now that you've seen the device work over cellular, you can optionally configure a WiFi network.

(Optional) Configure a WiFi Network

The Notecard inside the Blues OPTA expansion is a Cell+WiFI Notecard, so it’s possible to configure the expansion to use a 2.4 GHz WiFi Network as a primary backhaul, with cellular as a failover. Note that 5GHz WiFi networks are not supported. If you wish to use a local WiFi network for your testing, you can send the following command to the Notecard via the terminal:

{
  "req":"card.wifi",
  "ssid": "YOUR-NETWORK-SSID",
  "password": "YOUR-PASSWORD"
}

note

You can use the Notecard's card.transport request to configure which connectivity protocol your Notecard should use.

The default value of the request is "wifi-cell", which tells the Notecard to prioritize WiFi connectivity, and to fallback to cellular connectivity if a WiFi connection cannot be established.

Regardless of which method of connectivity you use, now that your expansion is communicating with Notehub you're now ready to physically connect the expansion to your OPTA.

Connecting Your OPTA

Let's connect some hardware!

To start, get out your OPTA and locate the AUX port on the right-hand side. If you have a cover on this port you need to remove it (it comes off pretty easily with a screwdriver).

Next, grab your OPTA expansion, and connect it to the right side of your OPTA as shown in the photo below.

note

Make sure the connection between the two modules is snug, as the AUX connector facilitates an I2C connection between the OPTA and the Notecard within the expansion module.

With everything connected you next need to provide power, and to do that you have two options.

Option 1) Bench Power Supply (Recommended)

The most robust way to power the OPTA is by connecting an external +12 VDC to +24 VDC power supply to the OPTA's power supply terminals (see the OPTA instruction manual). If your power supply's clips won't fit in the terminal, you may need to use loose pins or headers as I'm doing in the image below.

note

The OPTA uses combo Phillips/flathead screws, and the Blues OPTA expansion uses flathead screws. If you use a flathead screwdriver you can loosen/tighten the screws on both devices.

With the OPTA powered, next, connect the voltage from the OPTA to the expansion using rated jumper wires (typically 18AWG) as shown below.

And that's it! You should have everything you need in place to power both the OPTA and the Blues OPTA expansion.

As one last step, connect a USB-C cable from your OPTA to the computer you're using to complete this guide. When using a bench power supply the USB cable won't provide power, but you will need it to flash firmware onto the OPTA.

Option 2) USB Power

note

The OPTA's output ports are not powered via its USB-C port, therefore using USB for power should only be done during early development. For more, see Powering the OPTA.

As a second option you may use two USB-C connections to independently power the OPTA and Blues OPTA expansion.

The other end of the OPTA's cable must be connected to the computer you're using to complete this guide, as you'll need that connection to flash firmware in the next section. And if you're using USB cables for power, we additionally recommend connecting both USB cables to the same computer, as it ensures the devices share a common ground.

Regardless of how you power your devices, your hardware setup is now complete and you're ready to write firmware.

Writing Firmware

In this section you'll learn how to write firmware for your OPTA that uses the Blues OPTA expansion.

The Finder OPTA Codesys included in the bundle ships with the CODESYS runtime installed, and you have two options for programming it:

• CODESYS — Program the OPTA with IEC 61131-3 languages (Structured Text, Ladder Diagram, Function Block Diagram, and so on) using the CODESYS development environment.

• Arduino IDE — Replace the OPTA's CODESYS runtime with Arduino firmware, and program the OPTA with C++ sketches and Blues' note-arduino library.

Both options can communicate with the Notecard in the Wireless for OPTA, which is connected to the OPTA over I2C. Choose the tab that matches how you'd like to work.

tip

Let AI write your firmware. Blues Expert MCP connects your AI coding assistant (Claude Code, GitHub Copilot, Cursor) directly to our API docs, providing live request validation and firmware best practices for Arduino, C, Zephyr, and Python. Install the Blues Expert MCP →

CODESYS

Set Up CODESYS

Finder maintains the documentation for programming the OPTA with CODESYS, so rather than repeat it here, we'll point you at the right places.

1. Download CODESYS and the OPTA Configurator plug-in from Finder's software page. CODESYS runs on Windows only.

2. Follow Finder's Installing the Finder OPTA Plug-in in CODESYS tutorial. It walks through installing the plug-in, configuring the CODESYS Gateway to use your OPTA's USB serial port, and confirming that CODESYS can find your OPTA with Scan Network.

3. Create a project and download a simple program to the OPTA. Finder's CODESYS tutorials and the OPTA Codesys Instruction Manual cover the basics of working with the OPTA's inputs, relay outputs, and communication ports.

Communicating With the Notecard

The Wireless for OPTA connects the Notecard to the OPTA's I2C bus through the AUX connector. CODESYS supports I2C through an I2C master device and the I2C_Template library, as shown in the CODESYS I2C example.

The Notecard listens at I2C address 0x17 and uses a simple framing protocol for sending and receiving JSON requests, which is documented in the Serial-Over-I2C Protocol guide (see also Notecard Communication Without a Library). With that, you can send any Notecard API request from Structured Text.

Once you have data flowing from the Notecard to Notehub, skip ahead to Routing Your Data.

Arduino IDE

warning

Flashing Arduino firmware onto a Finder OPTA Codesys replaces its CODESYS runtime. After you complete the steps below, the OPTA will no longer be visible to CODESYS, and will instead behave like an Arduino-programmable OPTA.

If you need to keep using CODESYS on this OPTA, use the CODESYS tab instead.

Install the OPTA Board Package

Start by downloading and installing Arduino IDE if you haven't already.

Once installed, open Arduino IDE, click the Boards Manager icon in the left sidebar, search for “opta”, and install the latest version of Arduino Mbed OS OPTA Boards.

note

If you're on a Mac with Apple Silicon and see bad CPU type in executable when compiling, the OPTA board package's toolchain needs Rosetta 2. Install it by running softwareupdate --install-rosetta --agree-to-license in Terminal, then try again.

Enter Bootloader Mode (Finder OPTA Codesys Only)

Arduino IDE can't reboot a Finder OPTA Codesys into its bootloader on its own, so before your first upload you need to do it manually:

1. Connect a USB-C cable from your OPTA to your computer.

2. Quickly press the OPTA's RESET button twice (a "double tap"). The RESET button is recessed, so use the tip of a safety pin or toothpick.

The OPTA is now in bootloader mode and ready to accept an upload. You only need to do this once: after the first Arduino sketch is flashed, Arduino IDE can reboot the OPTA automatically for subsequent uploads, just like an Arduino Opta.

note

If you have an Arduino Opta, or a Finder OPTA Arduino Pro (types 8A.04.9.024.8300, 8310, or 8320), skip this step.

Hello World Example

Replace the contents of your sketch (the .ino file that's open by default) with the code below, which is a basic firmware example that blinks one of the OPTA built-in LEDs.

COPY

void setup() {
  // Initialize LED_BUILTIN as an output
  pinMode(LED_BUILTIN, OUTPUT);
}

void loop() {
  // Turn the LED_BUILTIN ON
  digitalWrite(LED_BUILTIN, HIGH);
  delay(1000);
  // Turn the user LED_BUILTIN OFF
  digitalWrite(LED_BUILTIN, LOW);
  delay(1000);
}

Ensure you have a USB-C cable connected from your OPTA to your computer, and then press the Upload button in Arduino IDE to flash the firmware to your device.

If all went well you should see the LED above the OPTA's RESET button blink on and off every one second.

Upload failing?

• If the output ends with Waiting for upload port... followed by dfu-util: No DFU capable USB device available, the OPTA isn't in bootloader mode. Double tap the RESET button as described above and try the upload again.

Notecard Example

Now that you know how to build firmware and flash it to your device, you're ready to start working with the Notecard. To do so, you first need to install note-arduino, the official Notecard Arduino library from Blues.

To install note-arduino, go to the libraries tab in Arduino IDE, search for “blues”, and install the latest version of the Blues Wireless Notecard library.

With note-arduino installed, you now have access to its full API for interacting with the Notecard.

To try it out, replace the contents of your sketch with the code below, which uses a few new Notecard requests to send a temperature and voltage reading to Notehub every 15 seconds.

COPY

#include <Notecard.h>

#define usbSerial Serial

Notecard notecard;

void setup() {
    usbSerial.begin(115200);
    const size_t usb_timeout_ms = 3000;
    for (const size_t start_ms = millis(); !usbSerial && (millis() - start_ms) < usb_timeout_ms;)
        ;
    notecard.setDebugOutputStream(usbSerial);

    notecard.begin();
}

void loop() {
  takeReading();
  delay(15 * 1000);
}

void takeReading() {
  double temperature = 0;
  
  {
    J *rsp = notecard.requestAndResponse(notecard.newRequest("card.temp"));
    if (rsp != NULL)
    {
      temperature = JGetNumber(rsp, "value");
      notecard.deleteResponse(rsp);
    }
  }

  double voltage = 0;
  {
    J *rsp = notecard.requestAndResponse(notecard.newRequest("card.voltage"));
    if (rsp != NULL)
    {
      voltage = JGetNumber(rsp, "value");
      notecard.deleteResponse(rsp);
    }
  }

  {
    J *req = notecard.newRequest("note.add");
    if (req != NULL)
    {
      JAddBoolToObject(req, "sync", true);
      J *body = JAddObjectToObject(req, "body");
      if (body != NULL)
      {
        JAddNumberToObject(body, "temp", temperature);
        JAddNumberToObject(body, "voltage", voltage);
      }
      notecard.sendRequest(req);
    }
  }
}

Let's break down this code in detail. The takeReading() function starts by gathering two different values from the Notecard. The first call uses the Notecard's card.temp request to take a reading from the Notecard's onboard temperature sensor.

COPY

double temperature = 0;
{
  J *rsp = notecard.requestAndResponse(notecard.newRequest("card.temp"));
  if (rsp != NULL)
  {
    temperature = JGetNumber(rsp, "value");
    notecard.deleteResponse(rsp);
  }
}

The second call uses the Notecard's card.voltage request to retrieve the current V+ voltage level from the Notecard.

COPY

double voltage = 0;
{
  J *rsp = notecard.requestAndResponse(notecard.newRequest("card.voltage"));
  if (rsp != NULL)
  {
    voltage = JGetNumber(rsp, "value");
    notecard.deleteResponse(rsp);
  }
}

The final call takes these two values, and uses the Notecard's note.add request to queue a Note on the Notecard.

COPY

{
  J *req = notecard.newRequest("note.add");
  if (req != NULL)
  {
    JAddBoolToObject(req, "sync", true);
    J *body = JAddObjectToObject(req, "body");
    if (body != NULL)
    {
      JAddNumberToObject(body, "temp", temperature);
      JAddNumberToObject(body, "voltage", voltage);
    }
    notecard.sendRequest(req);
  }
}

By default, the Notecard acts as a queue that you can synchronize with the cloud using a number of different strategies.

In the case of this example, notice that we're including a sync=true option on the note.add request. This option tells the Notecard to immediately synchronize this Note to Notehub.

It's easier to understand what this code is doing after you see it in action. To try this firmware on your device, once again hit the Upload button in Arduino IDE to flash this updated sketch. Once the new code has been running for a minute or so, return to your Notehub project and visit its Events screen.

If all went well, you should see a running list of events with temperature and voltage readings from your device.

note

If you open the Serial Monitor in Arduino IDE, you can also see a running log of the requests and responses from the Notecard.

This is the most common workflow when using the Notecard. To take sensor readings from your device at a certain interval, you queue that data on your Notecard as Notes, and you tell the Notecard how often to synchronize that data with the cloud.

The power of the Notecard is you don't have to worry about the underlying connectivity. In fact, this exact same code works regardless of whether your Notecard is using a WiFi or cellular connection!

Now that you have data flowing in from your device, let's look at what you may want to do with it.

Routing Your Data

Once you have data flowing from your Notecard to Notehub, you can use Notehub’s routing capability to send data to and from your cloud application of choice.

Notehub supports a wide variety of route types, including easy ways to send data over HTTP/HTTPS or MQTT, and powerful integrations with bigger clouds like AWS, Azure, and Google Cloud.

In this section you'll set up a basic HTTP/HTTPS route to see how routing in Notehub works.

Routing With HTTP/HTTPS

To create your first route you'll use webhook.site, an online service that lets you create an HTTPS endpoint and monitor all incoming requests.

After getting your Notehub route working with webhook.site, switching your route to use a custom endpoint is as easy as switching the URL. Let's see how it works.

1. Navigate to webhook.site. When the page loads, you'll be presented with a unique URL that you can use as a route destination. Copy that URL for the next step.

   

2. Open up your project on Notehub, and click on the Routes menu item in the left nav.

3. Click Create Route.

   

4. Select the General HTTP/HTTPS Request/Response route type.

   

5. Give the route a name (for example, "Health").

   

6. For the Route URL, use the unique URL you obtained from webhook.site.

   

7. Make sure the Enabled switch remains selected, and click Create Route.

8. Return to webhook.site. This page will update automatically with data from your Notecard as it is received in Notehub. Notice how your custom data is in the body attribute, but that the Notehub appends additional metadata to each request, such as a device's best location.

   

Routing With Other Services

A basic HTTP route is just one of many ways you can access your data from Notehub. For a guided tutorial through the other routing options, see our Routing Data to Cloud tutorial.

You can also use the RESTful Notehub API to access your event data. For more information on the Notehub API, see our Using the Notehub API tutorial.

Next Steps

In this tutorial you learned how to assemble your Blues Wireless for OPTA, how to configure the Notecard, how to write firmware that communicates over cellular, and how to manage your data in the cloud.

Even after all this, you're still scratching the surface of what the Notecard can do. Because the Blues OPTA expansion is Notecard-powered, you can complete any of this site's Notecard Guides to learn more about what you can do with the Notecard.

Additionally, you may wish to check out our many Example Apps for inspiration, or for a starting point for the app you want to build next.

If you have any questions along the way (or just show off something cool you built), reach out anytime in our community forum.

Reference

The following is reference information you may find useful as you work with your Wireless for OPTA expansion.

Default Configuration

Blues runs a series of Notecard requests on all new OPTA expansions. Knowing this default configuration can be useful if you choose to override the defaults, or if you factory reset your Notecard and wish to reapply the default configuration.

Monitor Mode

The Blues OPTA expansion includes a push button and Neopixel on the front panel that can be used for testing connectivity during installation or for debugging. The card.aux request configures the Notecard to "watch" for a GPIO button press and, when detected, send a message to Notehub in a reserved _button.qo Notefile. During transmission the Neopixel colors change to signal pending or successful transmission as documented here.

{
  "req":"card.aux",
  "mode":"neo-monitor",
  "sensitivity": 25
}

A successful communication test will appear in the Notehub events view like this:

Power Outage Detection

The Blues OPTA expansion includes a power-outage-detection capability via a built-in Lithium Ion Capacitor. What this means is that, when an outage is detected on the 12-24V power supply that feeds the expansion (and presumably the OPTA it is connected to), the Notecard will send an alert to Notehub that an outage has been detected, and this message can be routed to your cloud application.

This capability is configured with the Notecard's card.voltage request.

{
  "req":"card.voltage",
  "mode": "default",
  "alert": true,
  "sync": true
}

Notehub Connection Settings

In addition to setting the ProductUID for your device, the Notecard's hub.set request can also be used to perform additional configuration of the Notecard and how it interacts with Notehub. The default configuration for the expansion sets the Notecard to maintain a continuous connection to Notehub, and to sync every 15 minutes if there’s data to send.

{
  "req": "hub.set",
  "mode": "continuous",
  "outbound": 15,
  "inbound": 1440,
  "sync": true,
  "align":true
}

Using the Expansion QR Code

The Blues OPTA expansion includes a QR code sticker on the front face. This sticker is an additional feature of the Notecard that allows product builders to associate the Notecard with a dashboard or system for their users.

For example, the Blues Airnote has a printed QR code that users can scan to change an Airnote's settings, and to view a dashboard of device data.

To set up something similar for your product, see Creating a Device Dashboard.