🚀 Browse our open source reference applications to accelerate your IoT project!

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
×
HomeNotecardNotecard API ReferenceNotecard Guides
Notecard Firmware Updates
Notecard Walkthrough
Overview
Notecard Requests & Responses
JSON Fundamentals
Notecard Interfaces
Essential RequestsNotehub ConfigurationAdding Notes to NotefilesWorking with Environment VariablesInteracting with Notehub
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
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

Essential Requests

When building an embedded application with the Notecard, there are a number of essential API requests to know.

Notehub Configuration hub.set

Every Notecard must be configured for your project before it can sync data to Notehub. The hub.set request is used to:

  • Assign a Notehub ProductUID to the Notecard.
  • Optionally set a Serial Number for the Notecard.
  • Configure the synchronization mode between the Notecard and Notehub.

Setting a ProductUID & Serial Number

Most of the time, your first request to the Notecard in a new application will be to set the ProductUID. This is done with the hub.set request and product argument, which will correspond to a ProductUID pre-configured in Notehub. If the Notecard attempts to sync with a missing ProductUID, the device will be rejected by Notehub.

    {
      "req": "hub.set",
      "product": "your-productuid"
    }
    J *req = NoteNewRequest("hub.set");
    JAddStringToObject(req, "product", "your-productuid");
    
    NoteRequest(req);
    req = {"req": "hub.set"}
    req["product"] = "your-productuid"
    card.Transaction(req)

    Optionally, you can associate your product's serial number (as an arbitrary string) with the Notecard by using hub.set with the sn argument. This arbitrary field can be used to more easily identify devices in Notehub or your own cloud applications.

      {
        "req": "hub.set",
        "product": "your-productuid",
        "sn": "your-serial-number"
      }
      J *req = NoteNewRequest("hub.set");
      JAddStringToObject(req, "product", "your-productuid");
      JAddStringToObject(req, "sn", "your-serial-number");
      
      NoteRequest(req);
      req = {"req": "hub.set"}
      req["product"] = "your-productuid"
      req["sn"] = "your-serial-number"
      card.Transaction(req)

      Configuring Synchronization Modes

      The Notecard's connection to Notehub is configurable, and can be adjusted based on the battery and data needs of your application. The mode field of hub.set accepts the following values:

      • periodic - (Default) "On demand" mode. The Notecard will periodically power-on the modem and connect to Notehub whenever it needs to synchronize with the service, and will then power-off the modem when not in use.
      • continuous - Maintains an active network and Notehub connection. For Cellular Notecards this includes keeping the cellular modem powered on. For Wi-Fi Notecards this includes keeping an active connection to a Wi-Fi access point.
      • minimum - Disables automatic connection to Notehub. In this mode, you will need to manually send a hub.sync request to trigger a sync.
      • off - Disables both automatic and manual connection to Notehub. This is, in essence, the Notecard's "airplane mode" which ensures that the modem will not power-on under any circumstances.
        {
          "req": "hub.set",
          "mode": "minimum"
        }
        J *req = NoteNewRequest("hub.set");
        JAddStringToObject(req, "mode", "minimum");
        
        NoteRequest(req);
        req = {"req": "hub.set"}
        req["mode"] = "minimum"
        card.Transaction(req)

        In the case of both periodic and continuous sync modes, the Notecard will periodically synchronize both outbound and inbound data with Notehub using a timing algorithm set by the configured outbound and inbound "sync times" (see below). If your application is using continuous mode and is expecting inbound data from the service where responsiveness is key, adding the sync flag will cause inbound data from Notehub to be synchronized to the Notecard as soon as it is detected.

          {
            "req": "hub.set",
            "mode": "continuous",
            "sync": true
          }
          J *req = NoteNewRequest("hub.set");
          JAddStringToObject(req, "mode", "continuous");
          JAddBoolToObject(req, "sync", true);
          
          NoteRequest(req);
          req = {"req": "hub.set"}
          req["mode"] = "continuous"
          req["sync"] = True
          card.Transaction(req)

          Setting Sync Times for Outbound and Inbound Data

          After setting the synchronization mode, tune the frequency of outbound and inbound sync requests using the outbound and inbound arguments. These values are required if operating in periodic or continuous mode.

          The outbound argument configures the max wait time (in minutes) to sync outbound data, such as new Notes added by the host application. Data may sync more frequently, but the Notecard will never wait longer than this amount of time to initiate a sync, if data is awaiting upload. The value passed into this field must be an integer.

            {
              "req": "hub.set",
              "outbound": 60
            }
            J *req = NoteNewRequest("hub.set");
            JAddNumberToObject(req, "outbound", 60);
            
            NoteRequest(req);
            req = {"req": "hub.set"}
            req["outbound"] = 60
            card.Transaction(req)

            The inbound field configures the max wait time (in minutes) to sync inbound data, such as environment variables or inbound Notes from Notehub. Data may sync more frequently, but the Notecard will never wait longer than this amount of time to initiate a sync. The value passed into this field must be an integer.

              {
                "req": "hub.set",
                "inbound": 120
              }
              J *req = NoteNewRequest("hub.set");
              JAddNumberToObject(req, "inbound", 120);
              
              NoteRequest(req);
              req = {"req": "hub.set"}
              req["inbound"] = 120
              card.Transaction(req)

              Configuring Session Duration in Continuous Mode

              When the Notecard establishes a new session with Notehub, it syncs information (for example, signal strength and device location) that is not included in every individual Note. When operating in continuous mode, the Notecard maintains a connection to Notehub and does not end or start new sessions as long as the device is powered. If you need to obtain session-specific data on a periodic basis, use the duration argument, and provide an integer value to represent the session duration, in minutes.

                {
                  "req": "hub.set",
                  "mode": "continuous",
                  "duration": 240
                }
                J *req = NoteNewRequest("hub.set");
                JAddStringToObject(req, "mode", "continuous");
                JAddNumberToObject(req, "duration", 240);
                
                NoteRequest(req);
                req = {"req": "hub.set"}
                req["mode"] = "continuous"
                req["duration"] = 240
                card.Transaction(req)

                Once set, after the duration period elapses, the Notecard will gracefully drop the current session and immediately establish a new one to sync session information.

                note

                Combining Requests

                The prior requests, and the majority of requests in this guide, do not need to be performed separately. For instance, it's common for a host application to set all of these parameters on boot. This can be performed with the following request:

                  {
                    "req": "hub.set",
                    "product": "your-productuid",
                    "sn": "your-serial-number",
                    "mode": "continuous",
                    "outbound": 60,
                    "inbound": 120,
                    "duration": 240,
                    "sync": true
                  }
                  J *req = NoteNewRequest("hub.set");
                  JAddStringToObject(req, "product", "your-productuid");
                  JAddStringToObject(req, "sn", "your-serial-number");
                  JAddStringToObject(req, "mode", "continuous");
                  JAddNumberToObject(req, "outbound", 60);
                  JAddNumberToObject(req, "inbound", 120);
                  JAddNumberToObject(req, "duration", 240);
                  JAddBoolToObject(req, "sync", true);
                  
                  NoteRequest(req);
                  req = {"req": "hub.set"}
                  req["product"] = "your-productuid"
                  req["sn"] = "your-serial-number"
                  req["mode"] = "continuous"
                  req["outbound"] = 60
                  req["inbound"] = 120
                  req["duration"] = 240
                  req["sync"] = True
                  card.Transaction(req)

                  The result of all hub.set requests, if successful, is an empty JSON object ({}).

                  Adding Notes to Notefiles note.add

                  When you're ready to add data to your Notecard for synchronization, do so with the note.add request. This request adds a single Note with an arbitrary body or payload to a Notefile, which is an outbound queue of data to synchronize to Notehub.

                  By default, all Notes are added to the data.qo Notefile. The qo extension signifies that this is an outbound queue Notefile.

                    {
                      "req": "note.add",
                      "body": {"foo": "bar"}
                    }
                    J *req = NoteNewRequest("note.add");
                    J *body = JCreateObject();
                    JAddStringToObject(body, "foo", "bar");
                    JAddItemToObject(req, "body", body);
                    
                    NoteRequest(req);
                    req = {"req": "note.add"}
                    req["body"] = {"foo": "bar"}
                    rsp = card.Transaction(req)

                    The body field of a note.add request must be a valid JSON object. The contents of that object are up to you and can be fully customized for your application.

                      {
                         "req": "note.add",
                         "body": {
                            "foo": "bar",
                            "temp": 23.134,
                            "active": true
                         }
                      }
                      J *req = NoteNewRequest("note.add");
                      J *body = JCreateObject();
                      JAddStringToObject(body, "foo", "bar");
                      JAddNumberToObject(body, "temp", 23.134);
                      JAddBoolToObject(body, "active", true);
                      JAddItemToObject(req, "body", body);
                      
                      NoteRequest(req);
                      req = {"req": "note.add"}
                      req["body"] = {"foo": "bar", "temp": 23.134, "active": true}
                      rsp = card.Transaction(req)

                      Adding Notes to a Custom Notefile

                      If you wish to organize your Notes by function or type of data being captured, you can use the file field to specify a Notefile ID of your choosing, ending in a .qo extension.

                        {
                          "req": "note.add",
                          "body": { "foo": "bar" },
                          "file": "sensors.qo"
                        }
                        J *req = NoteNewRequest("note.add");
                        JAddStringToObject(req, "file", "sensors.qo");
                        
                        J *body = JCreateObject();
                        JAddStringToObject(body, "foo", "bar");
                        JAddItemToObject(req, "body", body);
                        
                        NoteRequest(req);
                        req = {"req": "note.add"}
                        req["file"] = "sensors.qo"
                        req["body"] = {"foo": "bar"}
                        rsp = card.Transaction(req)
                        warning

                        A qo or qos Notefile that does not use a Note Template is limited to 100 unsynced Notes. Attempting to add new Notes beyond this limit will result in this error:

                        {
                         "err": "error adding note: can't exceed 100 notes per file (currently 100; see note.template)"
                        }

                        This limit does not apply to qo or qos Notefiles that have a template, since the Notecard uses much less memory to store and sync templated Notes.

                        Adding Notes for Secure Transport

                        If you want to ensure that Notes are sent over encrypted TLS to Notehub, use the .qos extension. qos signifies that the Notefile is a secure outbound queue.

                          {
                            "req": "note.add",
                            "body": { "foo": "bar" },
                            "file": "sensors.qos"
                          }
                          J *req = NoteNewRequest("note.add");
                          JAddStringToObject(req, "file", "sensors.qos");
                          
                          J *body = JCreateObject();
                          JAddStringToObject(body, "foo", "bar");
                          JAddItemToObject(req, "body", body);
                          
                          NoteRequest(req);
                          req = {"req": "note.add"}
                          req["file"] = "sensors.qos"
                          req["body"] = {"foo": "bar"}
                          rsp = card.Transaction(req)

                          Adding Payloads to Notes

                          The Notecard can be used to upload data generated by host firmware that encodes data in a binary format. These applications can easily attach the Base64-encoded binary data to a Note by using the payload field.

                            {
                              "req": "note.add",
                              "payload": "ewogICAgInRlbXAiOiAyMy4xMzQKfQ=="
                            }
                            J *req = NoteNewRequest("note.add");
                            JAddStringToObject(req, "payload", "ewogICAgInRlbXAiOiAyMy4xMzQKfQ==");
                            
                            NoteRequest(req);
                            req = {"req": "note.add"}
                            req["payload"] = "ewogICAgInRlbXAiOiAyMy4xMzQKfQ=="
                            rsp = card.Transaction(req)

                            It's also possible to send both a body and a payload as a single Note.

                              {
                                "req": "note.add",
                                "body": { "foo": "bar" },
                                "payload": "ewogICAgInRlbXAiOiAyMy4xMzQKfQ=="
                              }
                              J *req = NoteNewRequest("note.add");
                              JAddStringToObject(body, "payload", "ewogICAgInRlbXAiOiAyMy4xMzQKfQ==");
                              J *body = JCreateObject();
                              JAddStringToObject(body, "foo", "bar");
                              JAddItemToObject(req, "body", body);
                              
                              NoteRequest(req);
                              req = {"req": "note.add"}
                              req["body"] = {"foo": "bar"}
                              req["payload"] = "ewogICAgInRlbXAiOiAyMy4xMzQKfQ=="
                              rsp = card.Transaction(req)

                              Initiating an Immediate Sync

                              If you want to initiate a sync immediately after adding a note, set the sync field to true.

                                {
                                  "req": "note.add",
                                  "body": {"foo": "bar"},
                                  "sync": true
                                }
                                J *req = NoteNewRequest("note.add");
                                JAddBoolToObject(req, "sync", true);
                                J *body = JCreateObject();
                                JAddStringToObject(body, "foo", "bar");
                                JAddItemToObject(req, "body", body);
                                
                                NoteRequest(req);
                                req = {"req": "note.add"}
                                req["body"] = {"foo": "bar"}
                                req["sync"] = True
                                rsp = card.Transaction(req)

                                The JSON response of all note.add requests, if successful, is the total number of Notes pending sync in the specified or default Notefile.

                                {"total":3}
                                note

                                Use Templates for your production apps

                                Working with ad-hoc Notes is a great way to get started with and build your Notecard-based prototypes. However, as your project gets closer to deployment and as you're working with more data, you'll want to use Templates for Notes and Notefiles. Templates allow you to define a schema for Notes, which the Notecard then uses to store data in smaller chunks for storage and transfer.

                                Working with Environment Variables

                                In IoT applications, many products require configuration variables or settings that can be used on an end device, but managed and updated once the product is deployed in the field. In addition, these products often need the ability to manage these values at multiple levels, from the device to a fleet or even an entire product and all of its deployed devices.

                                Environment variables are a Notecard and Notehub feature that enables settings synchronization that "just work," with no special setup or configuration needed. These variables are key-value pairs, can be set in Notehub and propagate to devices in a project or fleet, or set on a Notecard directly using the same synchronization mechanism used for Notes and Notefiles.

                                On the Notecard, env.get is used to obtain one or more environment variables and env.set is used to set a variable on that Notecard only, overriding any Notehub setting of that variable. env.default is used to set default values, on that Notecard, that are overwritten if that variable is also set at Notehub. Finally, env.modified is used to determine if any environment variables have changed.

                                Getting Environment Variables

                                Use the env.get request to retrieve all variables, a subset of variables or a single variable, by name. To get all variables, simply send an env.get request with no arguments.

                                  {
                                    "req": "env.get"
                                  }
                                  J *req = notecard.newRequest("env.get");
                                  
                                  notecard.sendRequest(req);
                                  req = {"req": "env.get"}
                                  
                                  rsp = card.Transaction(req)

                                  When requesting all variables, the Notecard returns each key-value pair in the body of the response object.

                                  {
                                   "body": {
                                    "monitor-pump": "true",
                                    "_tags": "office"
                                   },
                                   "time": "1656315835"
                                  }

                                  To retrieve a group of named environment variables, use the names field, and provide an array of variable names.

                                    {
                                      "req": "env.get",
                                      "names": ["monitor-pump","_tags"]
                                    }
                                    J *req = NoteNewRequest("env.get");
                                    
                                    J *names = JAddArrayToObject(req, "names");
                                    JAddItemToArray(names, JCreateString("monitor-pump"));
                                    JAddItemToArray(names, JCreateString("_tags"));
                                    
                                    NoteRequest(req);
                                    req = {"req": "env.get"}
                                    req["names"] = ["monitor-pump","_tags"]
                                    
                                    rsp = card.Transaction(req)

                                    To retrieve a single environment variable, use the name field to specify the variable you want.

                                      {
                                        "req": "env.get",
                                        "name": "monitor-pump"
                                      }
                                      J *req = NoteNewRequest("env.get");
                                      JAddStringToObject(req, "name", "monitor-pump");
                                      
                                      NoteRequest(req);
                                      req = {"req": "env.get"}
                                      req["name"] = "monitor-pump"
                                      
                                      rsp = card.Transaction(req)

                                      When requesting a single variable, the Notecard returns an object with a key of text and value corresponding to the variable name provided.

                                      {
                                       "text": "true",
                                       "time": "1656315835"
                                      }

                                      If the name provided does not match a known variable, or if no variables exist on the Notecard or Notehub, an empty JSON object ({}) is returned.

                                      To retrieve a single, all, or a group of environment variables after a modified time, pass a UNIX Epoch time in the time field of a env.get request.

                                        {
                                          "req": "env.get",
                                          "name": "monitor-pump",
                                          "time": "1656315835"
                                        }
                                        J *req = NoteNewRequest("env.get");
                                        JAddStringToObject(req, "name", "monitor-pump");
                                        JAddNumberToObject(req, "time", 1656315835);
                                        
                                        NoteRequest(req);
                                        req = {"req": "env.get"}
                                        req["name"] = "monitor-pump"
                                        req["time"] = 1656315835
                                        
                                        rsp = card.Transaction(req)

                                        If a variable or variables have changed, the Notecard will return them in the response. Otherwise, the Notecard will return an {env-not-modified} error.

                                        {
                                          "err": "environment hasn't been modified {env-not-modified}"
                                        }
                                        note

                                        The Hierarchy of Environment Variables

                                        Environment variables can be defined in a number of locations, from the Notecard, to Notehub device settings, the device's Fleet, and the Notehub project. Variables set at different levels of this hierarchy can override one another. When obtaining an environment variable, the Notecard uses the following priority order, where the first matched result is returned:

                                        1. The value set on that Notecard with the env.set request.
                                        2. The value set in Notehub directly on Notehub's record for the Device.
                                        3. The value set in Notehub on a Fleet to which the Device belongs.
                                        4. The value set in Notehub on the Project to which the Device belongs.
                                        5. The value set on that Notecard with the env.default request.

                                        Setting Environment Variable Defaults

                                        Use the env.default request to set a default value for the host. Once this value is set, it will be returned as defined by env.get unless the variable has been overridden by another env.set request or the Notehub.

                                        For instance, assume that you need to create a variable to determine whether your Host MCU should monitor a connected pump, and that you want to be able to override this value from your Notehub project. To set a default, you'd send the following request:

                                          {
                                            "req": "env.default",
                                            "name": "monitor-pump",
                                            "text": "true"
                                          }
                                          J *req = notecard.newRequest("env.default");
                                          JAddStringToObject(req, "name", "monitor-pump");
                                          JAddStringToObject(req, "text", "true");
                                          
                                          notecard.sendRequest(req);
                                          req = {"req": "env.default"}
                                          req["name"] = "monitor-pump"
                                          req["text"] = "true"
                                          
                                          card.Transaction(req)

                                          Then, your host can obtain this value using env.get:

                                            {
                                              "req": "env.get",
                                              "name": "monitor-pump"
                                            }
                                            J *req = NoteNewRequest("env.get");
                                            JAddStringToObject(req, "name", "monitor-pump");
                                            
                                            NoteRequest(req);
                                            req = {"req": "env.get"}
                                            req["name"] = "monitor-pump"
                                            
                                            rsp = card.Transaction(req)

                                            Which returns the following:

                                            {"text": "true"}

                                            If, in the future, a Notehub administrator wishes to disable monitoring without having to directly update the Notecard, they can do so by setting the monitor-pump variable directly in the Notehub UI. After the next sync, a env.get request will return this overridden value, and your host MCU can respond accordingly.

                                              {
                                                "req": "env.get",
                                                "name": "monitor-pump"
                                              }
                                              J *req = NoteNewRequest("env.get");
                                              JAddStringToObject(req, "name", "monitor-pump");
                                              
                                              NoteRequest(req);
                                              req = {"req": "env.get"}
                                              req["name"] = "monitor-pump"
                                              
                                              rsp = card.Transaction(req)

                                              Which returns the following:

                                              {"text": "false"}

                                              env.default can also be used to remove environment variables. Simply provide the variable name, but omit the text field, and the variable will be removed from the Notecard's internal storage.

                                                {
                                                  "req": "env.default",
                                                  "name": "monitor-pump"
                                                }
                                                J *req = notecard.newRequest("env.default");
                                                JAddStringToObject(req, "name", "monitor-pump");
                                                
                                                notecard.sendRequest(req);
                                                req = {"req": "env.default"}
                                                req["name"] = "monitor-pump"
                                                
                                                card.Transaction(req)

                                                The result of all env.default requests, if successful, is an empty JSON object ({}).

                                                Setting Environment Variables on the Notecard

                                                Use the env.set request to set an environment variable only on the Notecard. This variable will be returned in env.get requests, and sent to Notehub in the next sync, but cannot be overridden by Notehub.

                                                To set a variable, the name and text fields are used to set the variable name and value, respectively.

                                                  {
                                                    "req": "env.set",
                                                    "name": "monitor-pump",
                                                    "text": "false"
                                                  }
                                                  J *req = notecard.newRequest("env.set");
                                                  JAddStringToObject(req, "name", "monitor-pump");
                                                  JAddStringToObject(req, "text", "false");
                                                  
                                                  notecard.sendRequest(req);
                                                  req = {"req": "env.set"}
                                                  req["name"] = "monitor-pump"
                                                  req["text"] = "false"
                                                  
                                                  card.Transaction(req)

                                                  env.set can also be used to remove environment variables. Simply provide the variable name, but omit the text field, and a locally-defined variable will be removed from the Notecard's internal storage.

                                                    {
                                                      "req": "env.set",
                                                      "name": "monitor-pump"
                                                    }
                                                    J *req = notecard.newRequest("env.set");
                                                    JAddStringToObject(req, "name", "monitor-pump");
                                                    
                                                    notecard.sendRequest(req);
                                                    req = {"req": "env.set"}
                                                    req["name"] = "monitor-pump"
                                                    
                                                    card.Transaction(req)

                                                    The result of all env.set requests, if successful, is an empty JSON object, ({}).

                                                    Checking for Environment Variable Changes

                                                    When working with multiple environment variables on a device, it can become cumbersome for the host to continually check each variable to determine which values have changed. In these cases, use env.modified to obtain the time of the last update to any environment variable managed by the Notecard.

                                                      {
                                                        "req": "env.modified"
                                                      }
                                                      J *req = notecard.newRequest("env.modified");
                                                      
                                                      notecard.sendRequest(req);
                                                      req = {"req": "env.modified"}
                                                      
                                                      card.Transaction(req)

                                                      The result, if successful, is an empty JSON object ({}) if the Notecard is not tracking any environment variables, or a UNIX epoch timestamp indicating the last time any environment variable was changed on the device.

                                                      {
                                                        "time": 1605814493
                                                      }

                                                      When performing this request periodically, if the time value is unchanged between requests, it indicates that no environment variables have changed since the last request.

                                                      Alternatively, you can supply a time field in an env.modified request to determine whether the Notecard has detected an environment variable change since a known epoch time.

                                                        {
                                                          "req": "env.modified",
                                                          "time": 1605814493
                                                        }
                                                        J *req = NoteNewRequest("env.modified");
                                                        JAddNumberToObject(req, "time", 1605814493);
                                                        
                                                        NoteRequest(req);
                                                        req = {"req": "env.modified"}
                                                        req["time"] = 1605814493
                                                        
                                                        rsp = card.Transaction(req)

                                                        In response, the Notecard will return either a response with the time of a change or an {env-not-modified} error.

                                                        {
                                                          "err": "environment hasn't been modified {env-not-modified}"
                                                        }
                                                        note

                                                        env.modified does not indicate which environment variable on the Notecard has changed, only that a local variable has been modified. Use env.get to retrieve the latest variable values after issuing this request, if needed.

                                                        Interacting with Notehub

                                                        In addition to providing interfaces for setting synchronization settings on the Notecard, the hub API provides a number of requests for getting settings, initiating syncs and sending logs to Notehub.

                                                        Getting Service Configuration Parameters

                                                        To check all of the current configuration parameters on the Notecard, use the hub.get request:

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

                                                          The Notecard will return an object with the DeviceUID, ProductUID, and Serial number of your Notecard, as well as the Notehub host, mode, outbound, and inbound max sync time values.

                                                          {
                                                           "device": "dev:0000000000000000",
                                                           "product": "com.your-company.your-name:your_product",
                                                           "mode": "continuous",
                                                           "outbound": 60,
                                                           "inbound": 120,
                                                           "host": "a.notefile.net",
                                                           "sn": "your-serial-number",
                                                           "sync": true
                                                          }

                                                          Getting Service Connection Status

                                                          If you want to check on the status of your Notecard's connection to the network and Notehub, use the hub.status request:

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

                                                            This request will return an object with:

                                                            • status - The current status of the Notecard's network connection.
                                                            • connected - A boolean indicating whether the Notecard is connected to Notehub.
                                                            {
                                                             "status": "connected (session open) {connected}",
                                                             "connected": true
                                                            }

                                                            Initiating a Notehub Sync

                                                            If you need to manually initiate a sync between your Notecard and Notehub, you can do so with the hub.sync request. If your Notecard is set to minimum mode, this request must be issued to trigger a sync. If your Notecard is set to off mode, this request will be ignored.

                                                              {
                                                                "req": "hub.sync"
                                                              }
                                                              J *req = NoteNewRequest("hub.sync");
                                                              
                                                              NoteRequest(req);
                                                              req = {"req": "hub.sync"}
                                                              
                                                              card.Transaction(req)

                                                              The result of a hub.sync request, if successful, is an empty JSON object ({}).

                                                              If you wish to check on the status of a recently triggered or previous sync, you can do so with the hub.sync.status request.

                                                                {
                                                                  "req": "hub.sync.status"
                                                                }
                                                                J *req = NoteNewRequest("hub.sync.status");
                                                                
                                                                NoteRequest(req);
                                                                req = {"req": "hub.sync.status"}
                                                                
                                                                rsp = card.Transaction(req)

                                                                In response, the Notecard will return an object that varies based on the conditions of the request.

                                                                A sync in-progress will return the status of the sync, and the requested field, which represents the number of seconds since the sync was initiated.

                                                                {
                                                                 "status": "starting communications {wait-module} {connecting}",
                                                                 "requested": 8
                                                                }

                                                                A successful sync will return the status, along with the Unix epoch time when the sync was completed, and the completed field to represent the number of seconds since the sync completed:

                                                                {
                                                                 "status": "completed {sync-end}",
                                                                 "time": 1598367163,
                                                                 "completed": 1648
                                                                }

                                                                If the sync was triggered manually, the sync field will be returned and set to true:

                                                                {
                                                                 "status": "completed {sync-end}",
                                                                 "time": 1598367163,
                                                                 "sync": true,
                                                                 "completed": 1648
                                                                }

                                                                If an error occurs during a sync, the alert field is returned and set to true.

                                                                {
                                                                 "status": "merge notefile: sensors.qo",
                                                                 "time": 1598371227,
                                                                 "alert": true,
                                                                 "completed": 37
                                                                }

                                                                You can also trigger a sync through a call to hub.sync.status by setting the sync field to true. This auto-initiates the sync if the Notecard has 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)

                                                                  Sending Log Messages to Notehub

                                                                  If you need to send log messages from the Notecard to Notehub, you can do so with the hub.log request. These messages are added as Notes in a special _health.qo Notefile and sent to Notehub on the next sync.

                                                                    {
                                                                      "req": "hub.log",
                                                                      "text": "Hello World!"
                                                                    }
                                                                    J *req = NoteNewRequest("hub.log");
                                                                    JAddStringToObject(req, "text", "Hello World!");
                                                                    
                                                                    NoteRequest(req);
                                                                    req = {"req": "hub.log"}
                                                                    req["text"] = "Hello World!"
                                                                    
                                                                    card.Transaction(req)

                                                                    To mark the message as urgent, use the alert field:

                                                                      {
                                                                        "req": "hub.log",
                                                                        "text": "something is wrong!",
                                                                        "alert": true
                                                                      }
                                                                      J *req = NoteNewRequest("hub.log");
                                                                      JAddStringToObject(req, "text", "something is wrong");
                                                                      JAddBoolToObject(req, "alert", true);
                                                                      
                                                                      NoteRequest(req);
                                                                      req = {"req": "hub.log"}
                                                                      req["text"] = "something is wrong!"
                                                                      req["alert"] = True
                                                                      
                                                                      card.Transaction(req)

                                                                      If you need to trigger a sync immediately after queueing the message, set the sync field to true:

                                                                        {
                                                                          "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)

                                                                        The result of a hub.log request, if successful, is an empty JSON object ({}).

                                                                        Notecard InterfacesTime & Location Requests