Cellular, LoRa, and Wi-Fi: Introducing the Next Generation of Notecards

Blues Developers
What’s New
Resources
Accelerators
Fully documented reference applications
Blog
Technical articles for developers
Community
Community projects and resources
Terminal
Connect to a Notecard in your browser
Blues.ioNotehub.io
Shop
Docs
Button IconHelp
Notehub StatusVisit our ForumContact Support
Button IconSign In
Sign In
Sign In
Docs Home
What’s New
Resources
Accelerators
Fully documented reference applications
Blog
Technical articles for developers
Community
Community projects and resources
Terminal
Connect to a Notecard in your browser
Blues.ioNotehub.io
Shop
Docs
Notecard
Notecard API Reference
Notecard Guides
Notecard Firmware Updates
Notecard Walkthrough
Overview
Notecard Product Family
Notecard Requests & Responses
JSON Fundamentals
Notecard Interfaces
Essential Requests
Time & Location Requests
Inbound Requests & Shared Data
Web Transactions
Low Power Design
Low Bandwidth Design
Host Firmware Update Requests
Advanced Notecard Configuration
Notecard Error and Status Codes

Web Transactions

If your host needs to perform web requests with a 3rd party API or service, the Notecard can facilitate these requests with the web.get, web.put, web.post, and web.delete APIs. See complete details in the web Requests API reference.

Use of these requests in the Notecard API requires the following:

1) The Notecard must be in continuous mode and connected to Notehub.

For example:

{
  "req": "hub.set",
  "product": "com.your-company.your-name:your_product",
  "mode": "continuous"
}
J *req = NoteNewRequest("hub.set");
JAddStringToObject(req, "product", "com.your-company.your-name:your_product");
JAddStringToObject(req, "mode", "continuous");

NoteRequest(req);
req = {"req": "hub.set"}
req["product"] = "com.your-company.your-name:your_product"
req["mode"] = "continuous"

card.Transaction(req)

If any of the web.* requests are issued to a Notecard not in continuous mode or not connected, an error will be returned:

{ "err": "web operations require being online (hub.set)" }

2) The endpoint to the 3rd party API or service must be configured as a proxy Route in Notehub as a "Proxy for Device Web Requests" type.

This allows the host to avoid hardcoded URLs, keys, and certificates, while relying on Notehub secure authentication mechanisms for performing requests.

notehub proxy for web requests

Once the device is in continuous mode and the proxy Route is created, use web.get, web.put, web.post, or web.delete in accordance with the requirements of the final endpoint.

For example, the Route shown above creates a proxy to a GET request to the weather endpoint of the OpenWeatherMap API . The route argument corresponds to the Route Alias specified when the proxy Route is created.

{
  "req": "web.get",
  "route": "weatherInfo"
}
J *req = NoteNewRequest("web.get");
JAddStringToObject(req, "route", "weatherInfo");

NoteRequest(req);
req = {"req": "web.get"}
req["route"] = "weatherInfo"

rsp = card.Transaction(req)

For all web requests, the Notecard returns the HTTP Status Code in the result field. If the response also contains a body, that body is provided in the body field.

warning

The Notecard can only accept valid JSON in response to a GET, POST, or PUT request unless you override the default content argument of application/json with the appropriate MIME type.

{
 "result": 200,
 "body": {
  "base": "stations",
  "clouds": {
   "all": 75
  },
  "coord": {
   "lat": 42.5776,
   "lon": -70.87134
  },
  "name": "Beverly",
  "weather": [
   {
    "description": "broken clouds",
    "icon": "04d",
    "id": 803,
    "main": "Clouds"
   }
  ],
  "wind": {
   "deg": 240,
   "speed": 5.1
  }
 }
}
note

Data returned by a proxy Route is delivered to the Notecard unmodified. To preserve power and data, make sure the APIs you're working with return only the data needed by your host, if possible.

For web.put and web.post requests, a JSON body OR base64-encoded payload can be provided using the body or payload arguments. Unlike the note.add API, you cannot use both at the same time in a single web transaction.

{
  "req": "web.post",
  "route": "SensorService",
  "name": "/addReading",
  "body": { "temp": 72.32, "humidity": 32.2 }
}
J *req = NoteNewRequest("web.post");
JAddStringToObject(req, "route", "SensorService");
JAddStringToObject(req, "name", "/addReading");

J *body = JCreateObject();
JAddNumberToObject(body, "temp", 72.32);
JAddNumberToObject(body, "humidity", 32.2);
JAddItemToObject(req, "body", body);

NoteRequest(req);
req = {"req": "web.post"}
req["route"] = "SensorService"
req["name"] = "/addReading"
req["body"] = {"temp":72.32, "humidity":32.2}

rsp = card.Transaction(req)

After performing a web request, don't forget to set your Notecard back into a non-continuous mode, if needed, using hub.set.

Sending Large Payloads to Notehub

Consult our guide on Sending and Receiving Large Binary Objects if your application needs to send large binary payloads to Notehub.

Inbound Requests & Shared Data Low Power Design
Can we improve this page? Send us feedback
© 2023 Blues Inc.
© 2023 Blues Inc.
TermsPrivacy
Notecard Disconnected
Having trouble connecting?

Try changing your USB cable as some cables do not support transferring data. If that does not solve your problem, contact us at support@blues.com and we will get you set up with another tool to communicate with the Notecard.

Advanced Usage

The help command gives more info.

Connect a Notecard
Use USB to connect and start issuing requests from the browser.
Try Notecard Simulator
Experiment with Notecard's latest firmware on a Simulator assigned to your free Notehub account.

Don't have an account? Sign up