NearAPI Java Script Documentation
JavaScript API Features ( Alpha )
This page describes the Java Script API features intended to deploy applications in JavaScript code running from a simple browser.
Contents
- 1 Near API Code
- 2 DIG_OUTPUT
- 3 DIG_INPUT
- 4 WAIT_DIG_INPUT
- 5 ADC_INPUT
- 6 ADC_INPUT_CONFIG
- 7 RMS_INPUT
- 8 RMS_INPUT_CONFIG
- 9 PWM_OUTPUT
- 10 PULSE_OUTPUT
- 11 GET_PULSE_OUTPUT
- 12 TRIGGER_INPUT
- 13 TRIGGER_INPUT_CONFIG
- 14 DIG_COUNTER
- 15 DIG_COUNTER_CONFIG
- 16 DIG_ACCUMULATOR
- 17 DIG_ACCUMULATOR_RESET
- 18 NearTestAPIjs ( )
- 19 Near_Timer ( )
- 20 RESET_CHANNEL
- 21 RESET_MANUAL
- 22 SET_POOLING_TIME
- 23 API SPECIAL FEATURES
Near API Code
In order to run the NearAPI (v05) you should include the following line in your java script code.
<script type='text/javascript' src='http://nearbus.net/downloads/js_apps/nearapi_v05.js'></script>
Note: The NearAPIjs will return "DOWN" if the remote device has been disconnected.
DIG_OUTPUT
This function sets a channel (port) to the specified value.
Syntax : NearAPIjs ( (string) "service", (string) "device_id", (int) channel, (int) value ); service : DIG_OUTPUT device_id : the NearBus device identifier ( NB100xxx ). channel : the microcontroller platform (MCU) port. value : the value to set (0 or 1). Return : (string/int) this function returns "WAIT" while no data available, "DONE" on successful, "ERROR" if error.
DIG_INPUT
This function reads the value on a specified channel (port).
Syntax : NearAPIjs ( (string) "service", (string) "device_id", (int) channel, (int) value ); service : DIG_INPUT device_id : the NearBus device identifier ( NB100xxx ). channel : the microcontroller platform (MCU) port. value : the value to set (0 or 1). Return : (string/int) this function returns "WAIT" while no data available, the specified value (0 or 1) on successful, "ERROR" if error.
WAIT_DIG_INPUT
This function waits for a specified value on a specified channel (port).
Syntax : NearAPIjs ( (string) "service", (string) "device_id", (int) channel, (int) value ); service : WAIT_DIG_INPUT device_id : the NearBus device identifier ( NB100xxx ). channel : the microcontroller platform (MCU) port. value : the input value to wait for. Return : (string/int) this function returns "WAIT" while no data available, the read value (1 or 0) on successful, "ERROR" if error.
ADC_INPUT
This function reads the analog value with 10 bit resolution on a specified channel (port).
Syntax : NearAPIjs ( (string) "service", (string) "device_id", (int) channel, (int) value ); service : ADC_INPUT device_id : the NearBus device identifier ( NB100xxx ). channel : the microcontroller platform (MCU) port. value : the value to set (0 or 1). Return : (string/int) this function returns "WAIT" while no data available, a 10 bits Analog Input [ 0 to 1023 ] on successful, "ERROR" if error.
ADC_INPUT_CONFIG
This function configures the ADC reference value to 1100mV or 5000mV (default).
Syntax : NearAPIjs ( (string) "service", (string) "device_id", (int) channel, (int) value ); service : ADC_INPUT_CONFIG device_id : the NearBus device identifier ( NB100xxx ). channel : the microcontroller platform (MCU) port. value : this argument (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/int) this function returns "WAIT" while no data available, "DONE" on successful, "ERROR" if error.
RMS_INPUT
This function returns the True RMS value of the channel signal. It is indicated to measure signal up to 60 Hz and a peak signal value up tp 5000 mV. It is supported on PINs A0 to A6 on Arduino Platforms.
Syntax : NearAPIjs ( (string) "service", (string) "device_id", (int) channel, (int) value ); service : RMS_INPUT device_id : the NearBus device identifier ( NB100xxx ). channel : the microcontroller platform (MCU) port. value : None Return : (string/int) this function returns "WAIT" while no data available, the True RMS value of a balanced input signal (without DC component). on successful, "ERROR" if error.
RMS_INPUT_CONFIG
This function configures the ADC reference value to 1100mV or 5000mV (default).
Syntax : NearAPIjs ( (string) "service", (string) "device_id", (int) channel, (int) value ); service : RMS_INPUT_CONFIG device_id : the NearBus device identifier ( NB100xxx ). channel : the microcontroller platform (MCU) port. value : this argument (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/int) this function returns "WAIT" while no data available, "DONE" on successful, "ERROR" if error.
PWM_OUTPUT
This function generates a Pulse Width Modulated output (it allows to control servo motors).
Syntax : NearAPIjs ( (string) "service", (string) "device_id", (int) channel, (int) value ); service : PWM_OUTPUT device_id : the NearBus device identifier ( NB100xxx ). channel : the microcontroller platform (MCU) port. value : it ranges from 800 to 2200 (the standard servomotor duty cycle). Return : (string/int) this function returns "WAIT" while no data available, "DONE" on successful, "ERROR" if error.
PULSE_OUTPUT
This function generates Programmable Pulse Output of "x" milliseconds.
Syntax : NearAPIjs ( (string) "service", (string) "device_id", (int) channel, (int) value ); service : PULSE_OUTPUT device_id : the NearBus device identifier ( NB100xxx ). channel : the microcontroller platform (MCU) port. value : it represents the pulse duration in milliseconds. It ranges from 1 to (2^32) ( 1ms to 50 days ). Return : (string/int) this function returns "WAIT" while no data available, "DONE" on successful, "ERROR" if error.
GET_PULSE_OUTPUT
Returns the pulse output level (to figure out if the pulse has finished).
Syntax : NearAPIjs ( (string) "service", (string) "device_id", (int) channel, (int) value ); service : GET_PULSE_OUTPUT device_id : the NearBus device identifier ( NB100xxx ). channel : the microcontroller platform (MCU) port. value : None Return : (string/int) this function returns "WAIT" while no data available, the pulse output value (1 while the pulse is UP and 0 when it has finished), "ERROR" if error.
TRIGGER_INPUT
This function caches a trigger pulse on a digital input channel (port).
Syntax : NearAPIjs ( (string) "service", (string) "device_id", (int) channel, (int) value ); service : TRIGGER_INPUT device_id : the NearBus device identifier ( NB100xxx ). channel : the microcontroller platform (MCU) port. value : null. Return : (string/int) this function returns "WAIT" while no data available, 1 if a trigger was caught or 0 if not, "ERROR" if error.
TRIGGER_INPUT_CONFIG
This function configures the the trigger pulse edge.
Syntax : NearAPIjs ( (string) "service", (string) "device_id", (int) channel, (int) value ); service : TRIGGER_INPUT_CONFIG device_id : the NearBus device identifier ( NB100xxx ) channel : the microcontroller platform (MCU) port. value : it allows to configure the pulse edge: [1 -> rising_edge] [0 -> falling_edge]. Return : (string/int) this function returns "WAIT" while no data available, "DONE" on successful, "ERROR" if error.
DIG_COUNTER
This function counts pulses on the selected channel (over a specified period of time).
Syntax : NearAPIjs ( (string) "service", (string) "device_id", (int) channel, (int) value ); service : DIG_COUNTER device_id : the NearBus device identifier ( NB100xxx ). channel : the microcontroller platform (MCU) port. value : None Return : (string/int) this function returns "WAIT" while no data available, the accumulated input pulses (on falling edges) over a specified period of time ( from 1 to 50 days ), "ERROR" if error.
Features
- It 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_COUNTER_CONFIG
This function allows to set the counter period.
Syntax : NearAPIjs ( (string) "service", (string) "device_id", (int) channel, (int) value ); service : DIG_COUNTER_CONFIG device_id : the NearBus device identifier ( NB100xxx ). channel : the microcontroller platform (MCU) port. value : the counting period in ms, it ranges from 1 to 2^32( from 1ms to 50 days ). Return : (string/int) this function returns "WAIT" while no data available, "DONE" on successful, "ERROR" if error.
DIG_ACCUMULATOR
This function accumulates pulses on an input channel (port).
Syntax : NearAPIjs ( (string) "service", (string) "device_id", (int) channel, (int) value ); service : DIG_ACCUMULATOR device_id : the NearBus device identifier ( NB100xxx ). channel : the microcontroller platform (MCU) port. value : : it returns the accumulated pulses on the selected channel since last reset. Return : (string/int) this function returns "WAIT" while no data available, the accumulated input pulses (on falling edges) on successful, "ERROR" if error.
Features
- The NearBus will retains the accumulated pulses even if the remote device is reseted.
- It 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_ACCUMULATOR_RESET
This function resets the accumulator (sets to 0) on a specified channel (port).
Syntax : NearAPIjs ( (string) "service", (string) "device_id", (int) channel, (int) value ); service : DIG_ACCUMULATOR_RESET device_id : the NearBus device identifier ( NB100xxx ). channel : the microcontroller platform (MCU) port. value : 0 Return : (string/int) this function returns "WAIT" while no data available, "DONE" on successful, "ERROR" if error.
NearTestAPIjs ( )
This basic function allows you to use API commands in a "raw way" ( it is mainly intended to be used for testing and debugging ).
Syntax : NearTestAPIjs ( (string) "service", (string) "method", (string) "device_id", (int) channel, (int) value ); service : DIG_OUTPUT, DIG_INPUT, WAIT_DIG_INPUT, ADC_INPUT, ADC_INPUT_CONFIG, RMS_INPUT, RMS_INPUT_CONFIG, PWM_OUTPUT, PULSE_OUTPUT, GET_PULSE_OUTPUT, TRIGGER_INPUT, TRIGGER_INPUT_CONFIG, DIG_COUNTER, DIG_COUNTER_CONFIG, DIG_ACCUMULATOR, DIG_ACCUMULATOR_RESET. method : POST or GET. device_id : the NearBus device identifier ( NB100xxx ). channel : the microcontroller platform port. value : the value to set (with POST), nothing (with GET). Return : none.
Near_Timer ( )
This function allows to implement a delay of "x" seconds in the user's main loop.
Syntax : Near_Timer ( seconds, command ); seconds : the number of seconds to count. command : "RUN" and "RESET"(resets the timer).
RESET_CHANNEL
This function resets a specified channel (port).
RESET_MANUAL
This function resets the manual mode for the specified device.
Syntax : NearAPIjs ( (string) "service", (string) "device_id", (int) channel, (int) value ); service : RESET_MANUAL device_id : the NearBus device identifier ( NB100xxx ). channel : set to 0. value : set to 0. Return : (string/int) this function returns "WAIT" while no data available, "DONE" on successful, "ERROR" if error.
SET_POOLING_TIME
This function allows to change the NearBus pooling time period.
Not implemented.
API SPECIAL FEATURES
MODE PARAMETER
Syntax : NearAPIjs ( (string) "service", (string) "device_id", (int) channel, (int) value, "MODE" ); The NearAPI supports the following modes: "FULL" This option allows full access to the API features (Read/Write). It is the API default mode. "RONLY": This option allows to GET a value as a Read-Only call. That means that you will get the last value in the NearBus data base, but no update will be sent to the remote device. "FLUSH" This option will "flush" any previous request queued for the specified device (it works with GET and POST methods).
