NearAPI REST Documentation
Contents
REST API - VMCU MODE
In order to offer the simplest interface the NearBus system offers a RESTful API to control the remote devices. As RESTful implementation the API uses the GET method to read values from the remote device (eg. Digital Inputs or ADC) and uses the POST method to write values to the remote device (eg. Digital Outputs a PWM).
PoGET Feature (POST over GET)
In order to improve the code simplicity the NearBus system implements the PoGET feature that allows to use the GET method as a POST (adding the "method=POST" argument on the URL). This feature allows you to control your remote devices avoiding use XMLHttpRequest() and so bypassing the Same Origin Policy in your JavaScript code (and even using the browser's address bar as a traditional command line interface).
Enhanced NearAPI Features ( Alpha )
This page describes the last API enhanced features intended to deploy applications in JavaScript code running from a simple browser.
The API REST syntax call is the following:
Standard API http://nearbus.net/v1/api_vmcu_jsb/NB100***?user=****&pass=****&channel=0&service=DIG_OUTPUT&value=1&method=POST&reqid=0 http://nearbus.net/v1/api_vmcu_jsb/NB100***?pin=****&channel=0&service=DIG_OUTPUT&value=1&method=POST&reqid=0
Secure API (SSL) https://nearbus.net/v1/api_vmcu_jsb/NB100***?user=****&pass=****&channel=0&service=DIG_OUTPUT&value=1&method=POST&reqid=0 https://nearbus.net/v1/api_vmcu_jsb/NB100***?pin=****&channel=0&service=DIG_OUTPUT&value=1&method=POST&reqid=0
Note: in order to use the secure API (SSL) you should accept the NearBus certificated (a warning message could be displayed, because your browser will not recognize it).
- user: Your NearBus Web user
- pass: Your NearBus Web password
- pin: The NearBus PIN defined at device level (it replace user and password credentials)
- channel: NearBus channel [0-3]
- value: Service value (if apply)
- method: GET (read) / POST (write)
- reqid: Transaction identifier, to match a request and its response. For example to read a sensor with ADC_INPUT through multiple GETs, or to set (with feedback) an output through DIG_OUTPUT using a POST and a GET.
- This API service returns immediately the "actual value" in the NearBus Data Base.
- The API requires a “request_id” (reqid) in order to match the request with the response. If the "request_id" does not match with the "request_id" in the NearBus Data Base, the API return "NULL" (this means that you always will need make two requests in order to obtain a valid value (not NULL). This "twin-call" procedure allows to the API call returns immediately simplifying the way in which the system can be programmed under JavaScript.
- The NearAPI always will return a single value (a number or NULL if is no valid value).
SUPPORTED API SERVICES (supported on Arduino agent v08 onwards)
DIG_INPUT
- This call returns the digital value in the specified channel (port).
Supported Method:
POST: not implemented. GET: Argument: None Return: this call returns the port digital value [0 or 1].
DIG_OUTPUT
- This call sets the specified channel (port) to 1 or 0.
Supported Methods: POST: Argument: the digital value to set [0 or 1]. Return: (string) "DONE" (the request was successfully registered) or "ERROR" (the request was not registered). GET: Argument: None Return: this call returns the set value [0 or 1].
ADC_INPUT
- This call returns the ADC value with 10 bits resolution.
Supported Methods: POST: Allows to set the ADC reference value to 1100mV or 5000mV. Argument: the argument value (set to 1100) allows to configure the 1100mV internal reference (Not available on Arduino Leonardo). The default is 5000mV as ADC reference (or 3300mv on 3.3V boards). Return: (string) "DONE" (the request was successfully registered) or "ERROR" (the request was not registered). GET: Argument: None Return: this call returns a 10 bits Analog Input [ 0 to 1023 ].
PWM_OUTPUT
- This call generates a pulse width modulated output (it allows to control servo motors).
Supported Methods POST: Sets the PWM output Duty Cycle [800 to 2200]. Argument: the argument [value] ranges from 800 to 2200 (the standard servomotor duty cycle). Return: (string) "DONE" (the request was successfully registered) or "ERROR" (the request was not registered). GET: Returns the PWM configured value. Argument: None Return: this call returns the configured value (if Ok) or "NULL" while it is waiting from a remote response.
PULSE_OUTPUT
- This call generates Programmable Pulse Output of "x" milliseconds.
Supported Methods POST: Argument: the pulse duration should be indicated in the "value" argument [ 1 to 2^32 ] in ms ( from 1ms to 50 days ). Works in steps of 5 ms (system accuracy). Return: (string) "DONE" (the request was successfully registered) or "ERROR" (the request was not registered). GET: Argument: None Works in steps of 5 ms (system accuracy). Return: this call returns the pulse output value (1 while the pulse is UP and 0 when it has finished).
TRIGGER_INPUT
- This call caches a trigger pulse on a digital input PIN.
Supported Methods POST: Allows to set the trigger edge. Argument: The "value" argument allows to configure the pulse edge: [1 -> rising_edge] [0 -> falling_edge]. Return: (string) "DONE" (the request was successfully registered) or "ERROR" (the request was not registered). GET: Argument: None Return: this call returns "1" if a trigger was caught, "0" otherwise.
Features
- The input is configured in High Z (the external switch should include a Pull-Up or Pull-Down resistor).
RMS_INPUT
- This call returns the True RMS value of a port signal. Indicated to measure signal up to 60 Hz and a peak signal value of 1.1 Volt. Supported on PINs A0 to A6 on Arduino Platforms.
Supported Methods POST: Allows to set the ADC peak reference value to 1100mV or 5000mV. Argument: the argument value (set to 1100) allows to configure the 1100mV internal reference (Not available on Arduino Leonardo). The default is 5000mV as ADC reference (or 3300mv on 3.3V boards). Return: (string) "DONE" (the request was successfully registered) or "ERROR" (the request was not registered). GET: Returns the TRUE RMS (Root Mean Square) value of the input signal in [mV]. Argument: None Return: this call returns the True RMS value of a balanced input signal (without DC component).
DIG_COUNTER
- This call counts pulses on the selected channel.
Supported Methods: POST: Allows to set the counter period in ms Argument: the Period should be indicated in the "value" argument [ 1 to 2^32 ] in ms ( from 1ms to 50 days ). Return: (string) "DONE" (the request was successfully registered) or "ERROR" (the request was not registered). GET: Argument: None Return: this call returns the accumulated input pulses (on falling edges) over a specified period of time ( from 1 to 50 days ).
Features
- Works in steps of 5 ms (system accuracy). The input is configured with a Pull-Up resistor (20 K), intended to work with dry-contact switchs and open collector devices.
DIG_ACCUMUL
- This call accumulates pulses on an input channel.
Supported Methods: POST: Argument: a POST is used to reset the accumulated pulses. Return: (string) "DONE" (the request was successfully registered) or "ERROR" (the request was not registered). GET: Argument: None Return: this call returns the accumulated pulses on the selected channel since last reset ( POST ).
Features
- The NearBus will retains the accumulated pulses even if the remote device is reseted.
- Works in steps of 5 ms (system accuracy). The input is configured with a Pull-Up resistor (20 K), intended to work with dry-contact switchs and open collector devices.
RESET_PORT
- This call resets All services on a specified channel (port).
Supported Method: POST: Argument: None Return: (string) "DONE" (the request was successfully registered) or "ERROR" (the request was not registered).
- A new reqid identifier should be used to guarantee a consistent response.
MY_NBIOS_0
- This service will trigger the user defined function (MyDriver_0) in the Arduino code.
Supported Method: POST: Argument: the value to send, that will be received in the Arduino code as "setValue" argument. Return: (string) the Arduino user function returned value (in the *pRetValue pointer) or "ERROR".
- A new reqid identifier should be used to guarantee a consistent response, (or "0" to disable the "reqid" matching feature).
