NearAPI Java Script Documentation

From Nearwiki
Jump to: navigation, search


JavaScript API Features ( Alpha )


This page describes the Java Script API features intended to deploy applications in JavaScript code running from a simple browser.


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).