Help

The next paragraphs describe the main features that NearBus offer to you, in order to allows you to configure, supervise and troubleshooting the remote devices connections.

If you are going to configure the Arduino Ethernet platform for the first time, please try the App Note 1218 - Hello World example.

---

Devices List

This screen shows you a list of all devices configured for your user account, allowing you to see quickly which devices are UP and which are DOWN.

This screen shows you a list of all devices configured for your user account, allowing you to see in a fast way which devices are UP and which are DOWN.

From here you can access the following options for the selected device:

• Config Device: See the Device Configuration paragraph.

• Edit Device: See the New Device / Edit Device paragraph.

• Cosm Config: See COSM Configuration paragraph.

• Device Monitor: See Device Monitor paragraph.

---

Device Configuration

This screen allows you to set in manual mode each device and control the basic features of NearBIOS subsystem offers (this option is only available for channels 0 to 3):

AGENT DEBUG: This option allows you to activate and deactivate the remote Agent debug output (the terminal output on the Arduino platform). This option will turn on and turn off the Agent's activity LED (Pin 8 on the Arduino Platform).

MAN (Manual Mode)

This check allows you to set each channel in Manual Mode (to control it with the function field)

Functions

• UP: DIG_OUTPUT=1 - Digital Output

• DOWN: DIG_OUTPUT=0 - Digital Output

• DIG_INPUT: Digital Input (0 or 1)

• ADC_INPUT: 10 bits Analog Input (0 to 1023 for 0 to 1.1V). It uses the internal 1.1V reference

• PWM_OUTPUT: Pulse width modulated output expressed in [us] and configured to control servo motors. The typical range for servo motors is from 800 to 2200 [us].

• MY_NBIOS_0: This option allows you to trigger the Arduino custom defined function "MyNbios()" in a periodic way. The value set in the "value" field will be sent to the remote "MyNbios()" as argument. This feature is intended to work in conjuntion with the "Cosm Connector".

Value

This field should be set with the desired value for output functions (DIG_OUT or PWM). When input functions are configured (DIG_IN or ADC)this field returns the read value.

Channel

The following chart shows how each Arduino's pin is mapped to the channels

Channel 0 = Dig_pin 3 + Analog A0

Channel 1 = Dig_pin 5 + Analog A1

Channel 2 = Dig_pin 6 + Analog A2

Channel 3 = Dig_pin 9 + Analog A3

Note: It is possible to wire up the analog pins with the digital pins (because the analog pin are configured as inputs).

---

New Device / Edit Device

This screen allows you to create a new device (and delete it).

The main fields are:

• Device Name: Allows you to set a name ID for your new device (recomended)

• Location: Allows you to set the physical location (optional)

• Function: Allows you to set the device function (optional)

• Shared Secret: Set here the shared secret (mandatory length of 8). The same as you configured in the Arduino

• Callback Function: Allows you to define the web service (Back-End) that will work in a call-back mode.

• Refresh Rate: Allows you to set the pooling device period [ms]

The following fields are only showed in the Edit Device screen:

• Configured as VMCU: (default) Allows you to configure the VMCU mode (to control the MCU in manual mode)

• Delete Device: This option allows you to delete a device

• Device ID: It is a unique identifier for each device (NB1xxxxxx) that will be generated by the system (at configuration time and cannot be modified).

---

Device Statistics

This screen shows you the main statistics of each device (this feature is intended to be used in troubleshooting and system tuning).

---

Xively Configuration (former Cosm)

This screen allows you send to Xively (www.xively.com) the values received from or transmitted to the remote device over each channel (this feature is intended to be used in troubleshooting and system tuning)

• Stream ID: This field allows you to set the Cosm's datastream where you want to send the signal.

• IN / OUT: This option allows you to indicate if you want to send a readed value (input) from the remote device or the written value (output) to the remote device for each channel.

• Constant and Offset: The main advantage of this feature is that it allows you to apply a basic transfer function to your signal before sending it to cosm:

     f(x) = x * K + offset

• ON: This option allows you to turn on or off the data feed to Cosm.

• Cosm Feed and API Key: This option allows you to configure the required parameters to connect succesfully to www.cosm.com.

The following table shows an example of output sent to www.cosm.com (2 channels)

---

X-Control (Xively) NEW!!!

This screen allows you interconnect different NearBus device using the Xively Cloud Services as an interconnection HUB (of analog signals). This feature allows to POST data to Xively (WRITE) and to GET data from Xively (READ). Additionally this module allows you to process the signal with three basic transfer functions (Gain, Offset and Deadband).

The following picture shown the X-CONTROLLER screen configuration fields:

• Function: This field shown the Function configutaed over the Channel.

• Manual: This field shows if the channel is on manual mode or not. In order to work with this module the selected Channel should be in manual mode (mandatory).

• --> : Selecting this option allows you to configure that a remote-device's read signal (eg. with ADC_INPUT) be sent to a specific Xively Datastream.

• <-- : Selecting this option allows you to configure that a Xively read signal be sent to the a defined NearBus Function on a specified channel.

• Gaint, Offset and DeadBand: This feature allows you to apply a basic signal processing to the signal before connect it to Xively, or a NearBus Channel:

     f(x) = DeadBand( x * Gain + offset )

The DeadBand() function works as an Hysteresis Transfer Function, generating a digital output signal (1 or 0). The following example shown a generic deadband operation (with a -0,5 deadband not zero centred):

When the sensed signal drops below the bottom setting value in the hysteresis block (below 21,5 deg. C) , the output will be UP (1). In turn when the temperature rises over the top setting value in the hysteresis block ( over 22,5 deg. C) the output will go DOWN (0).

(in this example in order to center the sensed signal around 0 an offset of -21 should be configured)

IMPORTANT: The Deadband function only will work arround 0 (zero). That means that the specified parameter represents 1/2 of the deadband centred on 0. A negative deadband value will generate an inverted output.

• Filter: This feature allows you to apply a Digital Filter to the signal processed value in order to smoothing the output (First Order Digital Filter). The following picture shows a comparison between: (A) An output with filter and (B) and output without filter:

Features:

- The filter output will reach the 90% of its final value in approximately 16 refresh-time slots.

- The digital filtering is the first function applied in the signal processing chain.

• Stream ID: This field allows you to set the Xively datastream where you want to write/read the signal.

• Value: This field shown the signal value after processing.

• Connect: This option allows you to "connect" each NearBus channel to/from a Xively Data Stream.

• Xively Feed and API Key: This option allows you to configure the required parameters to connect succesfully to www.xively.com.

IMPORTANT: This feature only will work on devices with NearBus release v0.14 onwards.

---

X-Control V2 - Digital Signal Processing - NEW!!!

These features only will work on devices with NearBus release v0.15 onwards.

• DIGITAL FILTER: The X-Control v2 applies a Second Order Bessel Digital Filter that offers a better performance (noise mitigation and signal smoothing).

• DIFFERENTIAL PROCCESSING: This module allows you to apply a Differential proccessing over the signal (Inegration and Derivation):

INTEGR: The output signal will be the integral of the input signal. (eg: to obtain the Energy [KW/hr] from the instant power [W] measured from a Current transformer)

DERIV: The output signal will be the derivative of the input signal.

OFF: The module is desactivated (no proccessing is applied to the signal).

RESET: Set the initial values to zero (eg: to reset the output when working in Integration mode).

• OUTPUT LIMITER: This module when configured will limit the output signal to the set value. This feature is useful when you send data to Xively because its auto-scale feature can be useless when you are experimenting with wide flapping signals (the saturation peaks hide the valid readings).

OFF: The module is desactivated (no limitation is applied to the signal).

<value>: Here you should set the absolute value to limit  the signal (the system limits both positive and negative values). 

---

Device Monitor

This screen shows you the system data interchange for each device over the following interfaces:

NearHub <--> Device

NearApi <--> User App

AGENT DEBUG: (not shown) This option allows you to activate and deactivate the Agent debug output (the terminal output on the Arduino platform).

Note: this feature is intended to be used in troubleshooting and system tuning.

REMEMBER: If you are experimenting random errors with your code (usually on memory exhaustion conditions), verify that the #define parameters DEBUG_DATA, DEBUG_BETA and DEBUG_ERROR (in file NearBusxxx_xxx.cpp) are all set to 0 (in order to deactivate the output debug messages).

---

Changing User Configuration

In order to change your user configuration (password / email) you should "click" on the user name link in the DEVICES LIST screen, as showen in the following picture:

The EDIT USER screen allows you to change your account password and/or your notification email address:

---

REST API - VMCU MODE

For information about the VMCU mode please go to: NearAPI REST Documentation

---

REST API - TRANSPARENT MODE

Probably the most powerful feature of NearBus system is the Transparent mode working with RTESful. Under this mode the system allows you to exchange up to eight 32 bits registers (int) in each system call.

The API URL is the following:

http://www.nearbus.net/v1/api_transp

This interchange (or synchronization works) as a simple function call that you can do from your Arduino sketch, as a traditional function call.

There are 2 group of 8 (32 bits) registers each: rxChannel[ ] and txChannel[ ]:

The rxChannel[ ] is used to receive the data from the Cloud and the txChannel[ ] is used to send the data to the Cloud.

As you can see in the following example (to turn on and turn off the Arduino pin 3), there is no change in the way in which the sketch is programmed. The only requirement is to set the txChannel[ ] registers, then call the Agente.NearChannel() function and finally process the received values in the rxChannel[ ].

IMPORTANT: Remember to configure your NearBus device in "TRSNP" mode (uncheck the VMCU option) in the "EDIT DEVICE" configuration screen.

When calling the Agente.NearChannel() function, the data in the txChannel[ ] will be replicated in the NearHub data base Reg A (data from the Agent) and the rxChannel[ ] will be updated with a copy of the data in the NearHub data base Reg B (data to the Agent)

From the application point of view the data can be exchanged through the RESTful API calls, in a similar way as was shown in the VMCU mode.

The following examples shows the browser's command line (browser's address bar) that should be used to turn on and turn off the Arduino's pin 3 in the last example.

Turning ON the pin

http://nearbus.net/v1/api_transp/NB100xxx?user=****&pass=****&method=POST&reg00=1

Turning OFF the pin

http://nearbus.net/v1/api_transp/NB100xxx?user=****&pass=****&method=POST&reg00=0

Note: In order to simplify the example the unused registers have been avoided (the transp_api supports this syntax). The full example to turn on the pin should be:

http://nearbus.net/v1/api_transp/NB100xxx?user=****&pass=****&method=POST&reg00=1&reg01=0&reg02=0&reg03=0&reg04=0&reg05=0&reg06=0&reg07=0

---

If you are interested in trying the NearAPI please contact us at: info@nearbus.net

(*) This initial trial release has been deployed only for the Arduino Ethernet platform. We are deploying new Agent libraries for other Arduino boards and platforms with Ethernet and Wi-Fi connectivity.