😌 Learn How to Simplify Host Firmware Updates with the Notecard on February 2nd !

Search
Documentation Results
End of results
Community Results
End of results
Support
Blues.io
Notehub.io
Shop
Sign In
Search
Documentation Results
End of results
Community Results
End of results
Support
Blues.io
Notehub.io
Shop
×
HomeReference
Glossary
Hardware
System Notefiles
Notecard API
Introduction
card Requests
dfu Requests
env Requests
file Requests
hub Requestshub.device.signalhub.gethub.loghub.sethub.signalhub.statushub.synchub.sync.status
note Requests
web Requests
Notehub API
API Introduction
Billing Account API
Device API
Environment Variable API
Event API
File API
Fleet API
Note API
Product API
Project API
Route API
Rate this page  
  • ★
    ★
  • ★
    ★
  • ★
    ★
  • ★
    ★
  • ★
    ★
Can we improve this page? Send us feedbackRate this page
  • ★
    ★
  • ★
    ★
  • ★
    ★
  • ★
    ★
  • ★
    ★
© 2023 Blues Inc.Terms & ConditionsPrivacy
blues.ioTwitterLinkedInGitHubHackster.io
Disconnected
Notecard Disconnected
Having trouble connecting?

Try changing your Micro 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

hub Requests

The hub set of requests provide a variety of ways for a developer to configure and monitor the connection between the Notecard and Notehub.

hub.device.signal

warning

The hub.device.signal API has been deprecated in favor of the Send Device Signal Notehub API.

Send a signal from Notehub to a Notecard.

note

A Notecard can receive a signal with the hub.signal request.

Arguments

body

JSON object (optional)

The JSON object to send.

product

string

The ProductUID from a Notehub project.

device

string

The globally-unique DeviceUID of a device that currently exists within the specified ProductUID.

It can also accept a serial number by prefixing the serial number with sn:. Please note that the serial number must be URL encoded.

      curl -L 'https://api.notefile.net/req?product=com.product.name' -d \
              '{"req":"hub.device.signal","device":"dev:000000000000000", "body": {"example-key":"example-value"}}' -H "X-Session-Token:<token>"
      Response Members

      connected

      boolean

      true if the Notecard is connected to Notehub.

      Example Response
      {
        "connected": true
      }

      hub.get

      Retrieves the current Notehub configuration for the Notecard.

      Arguments
      None
          {
            "req": "hub.get"
          }
          J *req = NoteNewRequest("hub.get");
          
          NoteRequest(req);
          req = {"req": "hub.get"}
          rsp = card.Transaction(req)
          Response Members

          device

          string

          The DeviceUID for the Notecard.

          product

          string

          The ProductUID to which the Notecard is registered.

          mode

          string

          The current operating mode of the Notecard, as defined in hub.set.

          outbound

          integer

          The max wait time, in minutes, to sync outbound data from the Notecard.

          voutbound

          string

          If outbound is overridden with a voltage-variable value.

          inbound

          integer

          The max wait time, in minutes, to sync inbound data from Notehub.

          vinbound

          string

          If inbound has been overridden with a voltage-variable value.

          host

          string

          The URL of the Notehub host.

          sn

          string

          The serial number of the device, if set.

          sync

          boolean

          true if the device is in continuous mode and set to sync every time a change is detected.

          Example Response
          {
            "device":  "dev:000000000000000",
            "product": "com.your-company.your-name:your_product",
            "mode":    "periodic",
            "outbound": 60,
            "inbound":  240,
            "host":    "a.notefile.net",
            "sn":      "your-serial-number"
          }

          hub.log

          Add a "device health" log message to send to Notehub on the next sync.

          Arguments

          text

          string

          alert

          boolean

          true if the message is urgent.

          sync

          boolean

          true if a sync should be initiated immediately. Setting true will also remove the Notecard from certain types of penalty boxes.

              {
                "req": "hub.log",
                "text": "something is wrong!",
                "alert": true,
                "sync": true
              }
              J *req = NoteNewRequest("hub.log");
              JAddStringToObject(req, "text", "something is wrong");
              JAddBoolToObject(req, "alert", true);
              JAddBoolToObject(req, "sync", true);
              
              NoteRequest(req);
              req = {"req": "hub.log"}
              req["text"] = "something is wrong!"
              req["alert"] = True
              req["sync"] = True
              card.Transaction(req)
              Response Members
              None: an empty object {} means success.

              hub.set

              The hub.set request is the primary method for controlling the Notecard's Notehub connection and sync behavior.

              Arguments

              product

              string (optional)

              A Notehub-managed unique identifier that is used to match Devices with Projects. This string is used during a device's auto-provisioning to find the Notehub Project that, once provisioned, will securely manage the device and its data.

              host

              string (optional)

              The URL of the Notehub service. Use "-" to reset to the default value.

              mode

              string enumeration (optional)

              The Notecard's synchronization mode. Must be one of:

              periodic

              Periodically connect to the Notehub. This is the default value set on each Notecard after a factory reset.

              continuous

              Enables an always-on network connection, for high power devices. Outbound data still syncs periodically, unless specified in a Note or File request.

              minimum

              Disables periodic connection. The Notecard will not sync until it receives an explicit hub.sync request.

              off

              Disables automatic and manual syncs. hub.sync requests will be ignored in this mode.

              dfu

              For putting the Notecard in DFU mode for a host firmware update. This mode is effectively the same as off in terms of the Notecard's network and Notehub connections.

              sn

              string (optional)

              The end product's serial number.

              outbound

              integer (optional)

              The max wait time, in minutes, to sync outbound data from the Notecard.

              duration

              integer (optional)

              When in continuous mode, the amount of time, in minutes, of each session. When this time elapses, the Notecard gracefully ends the current session and starts a new one in order to sync session-specific data to Notehub.

              voutbound

              string (optional)

              Overrides outbound with a voltage-variable value. See Modem Power Management for more information on configuring voutbound.

              inbound

              integer (optional)

              The max wait time, in minutes, to sync inbound data from Notehub.

              vinbound

              string (optional)

              Overrides inbound with a voltage-variable value.

              align

              boolean (optional)

              Use true to align syncs on a regular time-periodic cycle.

              For example: Assuming outbound = 15 minutes, with align:true the Notecard will look at UTC time, and when it's an even multiple of 15, it will perform a sync. Without align (the default behavior), it will wait 15 minutes after the previously completed sync.

              sync

              boolean (optional)

              If in continuous mode, automatically and immediately sync each time an inbound Notefile change is detected on Notehub.

              on (Added in v.3.4.1)

              boolean (optional)

              If in periodic mode, temporarily switch to continuous mode so that the host can perform a web transaction. Ignored if the Notecard is already in continuous mode.

              seconds (Added in v.3.4.1)

              boolean (optional)

              If in periodic mode and using on above, the number of seconds to run in continuous mode before switching back to periodic mode. If not set, a default of 300 seconds is used. Ignored if the Notecard is already in continuous mode.

              off (Added in v.3.4.1)

              boolean (optional)

              Set to true to manually instruct the Notecard to resume periodic mode after a web transaction has completed.

                  {
                    "req": "hub.set",
                    "product": "com.your-company.your-name:your_product",
                    "sn": "Sprocket123"
                  }
                  J *req = NoteNewRequest("hub.set");
                  JAddStringToObject(req, "mode", "continuous");
                  JAddStringToObject(req, "product", "com.your-company.your-name:your_product");
                  JAddStringToObject(req, "sn", "Sprocket123");
                  
                  NoteRequest(req);
                  req = {"req": "hub.set"}
                  req["product"] = "com.your-company.your-name:your_product"
                  req["sn"] = "Sprocket123"
                  card.Transaction(req)
                    {
                      "req": "hub.set",
                      "mode": "continuous",
                      "outbound": 30,
                      "inbound": 60,
                      "duration": 240,
                      "sync": true
                    }
                    J *req = NoteNewRequest("hub.set");
                    JAddStringToObject(req, "mode", "continuous");
                    JAddNumberToObject(req, "outbound", 30);
                    JAddNumberToObject(req, "inbound", 60);
                    JAddNumberToObject(req, "duration", 240);
                    JAddBoolToObject(req, "sync", true);
                    
                    NoteRequest(req);
                    req = {"req": "hub.set"}
                    req["mode"] = "continuous"
                    req["outbound"] = 30
                    req["inbound"] = 60
                    req["duration"] = 240
                    req["sync"] = True
                    card.Transaction(req)
                      {
                        "req": "hub.set",
                        "mode": "periodic",
                        "outbound": 90,
                        "inbound": 240
                      }
                      J *req = NoteNewRequest("hub.set");
                      JAddStringToObject(req, "mode", "periodic");
                      JAddNumberToObject(req, "outbound", 90);
                      JAddNumberToObject(req, "inbound", 240);
                      
                      NoteRequest(req);
                      req = {"req": "hub.set"}
                      req["mode"] = "periodic"
                      req["outbound"] = 90
                      req["inbound"] = 240
                      card.Transaction(req)
                        {
                          "req": "hub.set",
                          "host": "a.mynotehub.net"
                        }
                        J *req = NoteNewRequest("hub.set");
                        JAddStringToObject(req, "host", "a.mynotehub.net");
                        
                        NoteRequest(req);
                        req = {"req": "hub.set"}
                        req["host"] = "a.mynotehub.net"
                        card.Transaction(req)
                          {
                            "req": "hub.set",
                            "mode": "periodic",
                            "voutbound": "usb:30;high:60;normal:90;low:120;dead:0",
                            "vinbound": "usb:60;high:120;normal:240;low:480;dead:0"
                          }
                          J *req = NoteNewRequest("hub.set");
                          JAddStringToObject(req, "mode", "periodic");
                          JAddStringToObject(req, "voutbound", "usb:30;high:60;normal:90;low:120;dead:0");
                          JAddStringToObject(req, "vinbound", "usb:60;high:120;normal:240;low:480;dead:0");
                          
                          NoteRequest(req);
                          req = {"req": "hub.set"}
                          req["mode"] = "periodic"
                          req["voutbound"] = "usb:30;high:60;normal:90;low:120;dead:0"
                          req["vinbound"] = "usb:60;high:120;normal:240;low:480;dead:0"
                          card.Transaction(req)
                          Response Members
                          None: an empty object {} means success.
                          More information:
                          • Notehub Configuration with hub.set

                          • Modem Power Management with Voltage Variable Modes

                          • Changing the Notehub Service Host

                          hub.signal

                          Receive a signal (a near-real-time note) from Notehub.

                          This request checks for an inbound signal from Notehub. If it finds a signal, this request returns the signal’s body and deletes the signal. If there are multiple signals to receive, this request reads and deletes signals in FIFO (first in first out) order.

                          warning

                          A Notecard must be in continuous mode and have its sync argument set to true to receive signals.

                          {
                            "req": "hub.set",
                            "mode": "continuous",
                            "sync": true
                          }
                          note

                          See our guide to Using Inbound Signals for more information on how to set up a host microcontroller or single-board computer to receive inbound signals.

                          Arguments
                          None
                              {"req": "hub.signal"}
                              J *req = NoteNewRequest("hub.signal");
                              
                              NoteRequest(req);
                              req = {"req": "hub.signal"}
                              rsp = card.Transaction(req)
                              Response Members

                              body

                              JSON object

                              The JSON body of a received signal.

                              connected

                              boolean

                              true if the Notecard is connected to Notehub.

                              signals

                              integer

                              The number of queued signals remaining.

                              Example Response
                              {
                                "body": {
                                  "example-key": "example-value"
                                },
                                "connected": true
                              }
                              More information:
                              • Sending Signals from Notehub with hub.device.signal
                              • Notehub Configuration with hub.set

                              hub.status

                              Displays the current status of the Notecard's connection to Notehub.

                              Arguments
                              None
                                  {"req": "hub.status"}
                                  J *req = NoteNewRequest("hub.status");
                                  
                                  NoteRequest(req);
                                  req = {"req": "hub.status"}
                                  rsp = card.Transaction(req)
                                  Response Members

                                  status

                                  string

                                  Details about the Notecard's connection status.

                                  connected

                                  boolean

                                  true if the Notecard is connected to Notehub.

                                  Example Response
                                  {
                                    "status":    "connected (session open) {connected}",
                                    "connected": true
                                  }

                                  hub.sync

                                  Manually initiates a sync with Notehub.

                                  Arguments

                                  allow

                                  boolean

                                  Set to true to remove the Notecard from certain types of penalty boxes (the default is false).

                                      {"req": "hub.sync"}
                                      J *req = NoteNewRequest("hub.sync");
                                      
                                      NoteRequest(req);
                                      req = {"req": "hub.sync"}
                                      card.Transaction(req)
                                      Response Members
                                      None: an empty object {} means success.

                                      hub.sync.status

                                      Check on the status of a recently triggered or previous sync.

                                      Arguments

                                      sync

                                      boolean (optional)

                                      true if this request should auto-initiate a sync pending outbound data.

                                          {
                                            "req": "hub.sync.status",
                                            "sync": true
                                          }
                                          J *req = NoteNewRequest("hub.sync.status");
                                          JAddBoolToObject(req, "sync", true);
                                          
                                          NoteRequest(req);
                                          req = {"req": "hub.sync.status"}
                                          req["sync"] = True
                                          rsp = card.Transaction(req)
                                          Response Members

                                          status

                                          string

                                          The status of the current or previous sync.

                                          time

                                          UNIX Epoch time

                                          Time of the last sync completion. Will only populate if the Notecard has completed a sync to Notehub to obtain the time.

                                          alert

                                          boolean

                                          true if an error occurred during the most recent sync.

                                          sync

                                          boolean

                                          true if the notecard has unsynchronized notes, or requires a sync to set its internal clock.

                                          completed

                                          integer

                                          Number of seconds since the last sync completion.

                                          requested

                                          integer

                                          Number of seconds since the last explicit sync request.

                                          Example Response
                                          {
                                            "status": "completed {sync-end}",
                                            "time": 1598367163,
                                            "alert": true,
                                            "sync": true,
                                            "completed": 1648
                                          }
                                          More information:
                                          • Initiating a Notehub Sync
                                          file Requestsnote Requests