Rate this page  

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

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.

      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
}

      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"
}

          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.

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

              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)

              true to align syncs onto a regular time-periodic cycle.

              sync

              boolean (optional)

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

              unsecure

              boolean (optional)

              If in continous mode, connect to Notehub without establishing a TLS connection (default is false). Learn more in Advanced Notecard Configuration.

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

                          Send and receive signals (near-real-time notes) between a Notecard and Notehub.

                          Invoking this request with a body argument sends a signal to Notehub in a _signal.qo Notefile. Signals are sent immediately, and are not subject to a Notecard’s configured outbound interval.

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

                          warning

                          A Notecard must be in continuous mode to send signals. To receive signals, the Notecard must additionally have its sync argument set to true.

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

                          If you’re using the Notecard with a host microcontroller or single-board computer, you can look for signals by polling hub.signal, or by having the Notecard perform an interrupt when it receives an inbound signal—which you can configure with the card.attn request.

                          Arguments

                          body

                          JSON object (optional)

                          A JSON object to send.

                          live

                          boolean (optional, default is false)

                          When in live mode, the Notecard does not store the signal in a Notefile to reduce latency, and to send signals on the network as fast as possible. Live signals do not appear as _signal.qo events in Notehub, but are still routed.

                              {"req": "hub.signal", "body": {"example-key": "example-value"} }
                              J *req = NoteNewRequest("hub.signal");

J *body = JCreateObject();
JAddNumberToObject(body, "example-key", "example-value");
JAddItemToObject(req, "body", body);

NoteRequest(req);
                              req = {"req": "hub.signal"}
req["body"] = {"example-key": "example-value"}
rsp = card.Transaction(req)
                                {"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.

                                Example Response
                                {
  "body": {
    "example-key": "example-value"
  },
  "connected": true
}
                                More information:

                                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
}

                                    Manually initiates a sync with Notehub.

                                    Arguments

                                    allow

                                    boolean

                                    Set to true to remove the Notecard from a network registration penalty box (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.

                                        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: