ArduinoJavaSerialRpc (ArduinoJavaSerialRpc 1.0.0 API)

java.lang.Object
- it.mauxilium.arduinojavaserialrpc.ArduinoJavaSerialRpc

```
public class ArduinoJavaSerialRpc
extends Object
```
This class implements a bidirectional communication with Arduino card in form of RPC (Remote Procedure Call) and RMI (Remote Method Invocation) through the serial port.
Due to resource limitations of Arduino card, only a few fixed signatures are available.

Java to Arduino (RPC)
A Java program that includes ArduinoJavaSerialRpc can call a function inside an Arduino sketch if:
1. The sketch includes the ArduinoSerialRpc library: "#include <ArduinoSerialRpc.h>"
2. The sketch function is registered using the "registerArduinoFunction" method.
3. The sketch registered function have one of the following signatures:
  - void methodName();
  - int methodName(int arg1, int arg2);
  - float methodName(float arg);
  - String methodName(String arg);
For example, a legal call could be:

libraryInstance = new ArduinoRpc("COM5", 9600); libraryInstance.connect(); libraryInstance.executeRemoteFunction("writeAction", 1811, 1118);

Arduino to Java (RMI)
An Arduino sketch can call a Java method without any registration, if:
1. The sketch includes: "#include <ArduinoSerialRpc.h>".
2. The required method is part of a class which extends ArduinoJavaSerialRpc.
3. The method signature is one of the following:
  - void methodName();
  - Integer methodName(Integer arg1, Integer arg2);
  - Float methodName(Float arg);
  - String methodName(String arg);
For example, a legal sketch could be:

ArduinoSerialRpc rpc("My Arduino"); rpc.executeRemoteMethod("printArduinoText", "Hello from Arduino");

PROJECT NOTE:
Any Java project which uses ArduinoJavaSerialRpc must include also the RxTx library (a copy of it may be found into: ArduinoJavaSerialRpc/RxTx/*).
Warning: Missing the RxTx inclusion produces an execution error like: gnu/io/NoSuchPortException

EXECUTION NOTE:
In order to execute a Java program which includes ArduinoJavaSerialRpc, the command line must includes a driver link, like:
java -Djava.library.path=RxTx\mfz-rxtx-2.2-20081207-win-x64 -cp target/test-classes;target/classes;RxTx/mfz-rxtx-2.2-20081207-win-x64/RXTXcomm.jar integration.java.IntegrationTest COM5 9600

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`DATA_RATE_115200`
`static int`	`DATA_RATE_1200`
`static int`	`DATA_RATE_14400`
`static int`	`DATA_RATE_19200`
`static int`	`DATA_RATE_2400`
`static int`	`DATA_RATE_28800`
`static int`	`DATA_RATE_300`
`static int`	`DATA_RATE_38400`
`static int`	`DATA_RATE_4800`
`static int`	`DATA_RATE_57600`
`static int`	`DATA_RATE_600`
`static int`	`DATA_RATE_9600`
`static String`	`LINUX_DEFAULT_PORT` Default port to use when the Operative System is Linux.
`static String`	`MAC_OS_DEFAULT_PORT` Default port to use when the Operative System is Mac OS.
`static String`	`RASPBERRY_PI_DEFAULT_PORT` Default port to use when the Platform is Raspberry PI.
`static String`	`WINDOWS_DEFAULT_PORT` Default port to use when the Operative System is Windows.
`static String`	`WINDOWS_USB_1` Port COM1, to be used when the Operative System is Windows.
`static String`	`WINDOWS_USB_2` Port COM2, to be used when the Operative System is Windows.
`static String`	`WINDOWS_USB_3` Port COM3, to be used when the Operative System is Windows.
`static String`	`WINDOWS_USB_4` Port COM4, to be used when the Operative System is Windows.
`static String`	`WINDOWS_USB_5` Port COM5, to be used when the Operative System is Windows.
`static String`	`WINDOWS_USB_6` Port COM6, to be used when the Operative System is Windows.

Constructor Summary

Constructors
Constructor and Description

ArduinoJavaSerialRpc(String portName, int baudRate)
Creates a connector to Arduino card.

Constructors
Constructor and Description
`ArduinoJavaSerialRpc(String portName, int baudRate)` Creates a connector to Arduino card.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`connect()` Creates a connection with the Arduino card.
`void`	`disconnect()` Release the serial port connected to the Arduino card.
`void`	`executeLocalMethod(String methodToDo)` Discovers and executes a method of the extending class.
`void`	`executeLocalMethod(String methodToDo, float arg)` Discovers and executes a method of the extending class.
`void`	`executeLocalMethod(String methodToDo, int arg1, int arg2)` Discovers and executes a method of the extending class.
`void`	`executeLocalMethod(String methodToDo, String arg)` Discovers and executes a method of the extending class.
`void`	`executeRemoteFunction(String functionName)` Executes a function (of Arduino sketch) with signature: void functionName();.
`float`	`executeRemoteFunction(String functionName, float argument)` Executes a method (of Arduino sketch) with signature: float functionName(float);
`Integer`	`executeRemoteFunction(String functionName, int arg1, int arg2)` Executes a function (of Arduino sketch) with signature: int functionName(int arg1, int arg2); For example: `ArduinoSerialRpc rpc; void setup() {` pinMode(2, OUTPUT); pinMode(3, OUTPUT); rpc.registerArduinoFunction("setLightIntensity", setBrightness); } // Callable method from Java program.
`String`	`executeRemoteFunction(String functionName, String argument)` Executes a function (of Arduino sketch) with signature: string functionName(string);
`int`	`getBaudRate()` Returns the used baud rate
`String`	`getCardName()` Returns the card identification declared into the sketch It is the string used as argument of ArduinoSerialRpc constructor into the sketch.
`String`	`getPortName()` Returns the used USB port name
`void`	`handlerReceivingException(Exception ex)` Overridable function called when an exception occurs during data reads from Arduino.
`static String[]`	`portScanner()` Discover the available serial ports in system.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - MAC_OS_DEFAULT_PORT
```
public static final String MAC_OS_DEFAULT_PORT
```
    Default port to use when the Operative System is Mac OS.
    Assigned value: MAC_OS_DEFAULT_PORT = "/dev/tty.usbserial-A9007UX1"
    
    See Also:
    
    Constant Field Values
  - RASPBERRY_PI_DEFAULT_PORT
```
public static final String RASPBERRY_PI_DEFAULT_PORT
```
    Default port to use when the Platform is Raspberry PI.
    Assigned value: RASPBERRY_PI_DEFAULT_PORT = "/dev/ttyACM0"
    
    See Also:
    
    Constant Field Values
  - LINUX_DEFAULT_PORT
```
public static final String LINUX_DEFAULT_PORT
```
    Default port to use when the Operative System is Linux.
    Assigned value: LINUX_DEFAULT_PORT = "/dev/ttyUSB0"
    
    See Also:
    
    Constant Field Values
  - WINDOWS_DEFAULT_PORT
```
public static final String WINDOWS_DEFAULT_PORT
```
    Default port to use when the Operative System is Windows.
    Assigned value: WINDOWS_DEFAULT_PORT = "COM5"
    
    See Also:
    
    Constant Field Values
  - WINDOWS_USB_1
```
public static final String WINDOWS_USB_1
```
    Port COM1, to be used when the Operative System is Windows.
    
    See Also:
    
    Constant Field Values
  - WINDOWS_USB_2
```
public static final String WINDOWS_USB_2
```
    Port COM2, to be used when the Operative System is Windows.
    
    See Also:
    
    Constant Field Values
  - WINDOWS_USB_3
```
public static final String WINDOWS_USB_3
```
    Port COM3, to be used when the Operative System is Windows.
    
    See Also:
    
    Constant Field Values
  - WINDOWS_USB_4
```
public static final String WINDOWS_USB_4
```
    Port COM4, to be used when the Operative System is Windows.
    
    See Also:
    
    Constant Field Values
  - WINDOWS_USB_5
```
public static final String WINDOWS_USB_5
```
    Port COM5, to be used when the Operative System is Windows.
    
    See Also:
    
    Constant Field Values
  - WINDOWS_USB_6
```
public static final String WINDOWS_USB_6
```
    Port COM6, to be used when the Operative System is Windows.
    
    See Also:
    
    Constant Field Values
  - DATA_RATE_300
```
public static final int DATA_RATE_300
```
    See Also:
    
    Constant Field Values
  - DATA_RATE_600
```
public static final int DATA_RATE_600
```
    See Also:
    
    Constant Field Values
  - DATA_RATE_1200
```
public static final int DATA_RATE_1200
```
    See Also:
    
    Constant Field Values
  - DATA_RATE_2400
```
public static final int DATA_RATE_2400
```
    See Also:
    
    Constant Field Values
  - DATA_RATE_4800
```
public static final int DATA_RATE_4800
```
    See Also:
    
    Constant Field Values
  - DATA_RATE_9600
```
public static final int DATA_RATE_9600
```
    See Also:
    
    Constant Field Values
  - DATA_RATE_14400
```
public static final int DATA_RATE_14400
```
    See Also:
    
    Constant Field Values
  - DATA_RATE_19200
```
public static final int DATA_RATE_19200
```
    See Also:
    
    Constant Field Values
  - DATA_RATE_28800
```
public static final int DATA_RATE_28800
```
    See Also:
    
    Constant Field Values
  - DATA_RATE_38400
```
public static final int DATA_RATE_38400
```
    See Also:
    
    Constant Field Values
  - DATA_RATE_57600
```
public static final int DATA_RATE_57600
```
    See Also:
    
    Constant Field Values
  - DATA_RATE_115200
```
public static final int DATA_RATE_115200
```
    See Also:
    
    Constant Field Values
- Constructor Detail
  - ArduinoJavaSerialRpc
```
public ArduinoJavaSerialRpc(String portName,
                            int baudRate)
```
    Creates a connector to Arduino card.
    The constructor requires two parameters, frequently used values are declared in the PORTs constants (like LINUX_DEFAULT_PORT) and DATA_RATE constants.
    This constructor instantiates the resource only, to establish a physical connection with the card a "connect()" invocation is required.
    
    Parameters:
    
    portName - The name of connection port; His syntax depends from the operating system in use.
    
    baudRate - The value for Serial port speed; His value must be the same of Serial.begin value in the sketch.
- Method Detail
  - connect
```
public void connect()
             throws ArduinoRpcInitializationError
```
    Creates a connection with the Arduino card.
    After this calls the USB port is locked and no other program can use it.
    In order to release the USB port a "disconnect()" call is required.
    
    Throws:
    
    ArduinoRpcInitializationError - In any case of connection or initialization error (i.e. wrong connection port specified).
  - disconnect
```
public void disconnect()
                throws IOException
```
    Release the serial port connected to the Arduino card.
    To establish a new connection a "connect()" call is required.
    
    Throws:
    
    IOException - In any case of closing errors.
  - portScanner
```
public static String[] portScanner()
```
    Discover the available serial ports in system.
    
    Returns:
    
    A list of available serial ports (free and used too).
  - getPortName
```
public String getPortName()
```
    Returns the used USB port name
    
    Returns:
    
    one of the legal values like "/dev/ttyUSB0" or "COM4"
  - getBaudRate
```
public int getBaudRate()
```
    Returns the used baud rate
    
    Returns:
    
    one of the legal values like DATA_RATE_300 or DATA_RATE_9600
  - getCardName
```
public String getCardName()
                   throws ArduinoRpcJavaFailsException
```
    Returns the card identification declared into the sketch It is the string used as argument of ArduinoSerialRpc constructor into the sketch.
    
    Returns:
    
    the registered card identification name
    
    Throws:
    
    ArduinoRpcJavaFailsException - In any case of communication error or java side problems.
  - executeRemoteFunction
```
public void executeRemoteFunction(String functionName)
                           throws ArduinoRpcJavaFailsException
```
    Executes a function (of Arduino sketch) with signature: void functionName();.
    
    Parameters:
    
    functionName - The name of Arduino's function to call.
    
    Throws:
    
    ArduinoRpcJavaFailsException - In any case of communication error or java side problems.
  - executeRemoteFunction
```
public Integer executeRemoteFunction(String functionName,
                                     int arg1,
                                     int arg2)
                              throws ArduinoRpcJavaFailsException
```
    Executes a function (of Arduino sketch) with signature: int functionName(int arg1, int arg2);
    
    For example:
    
    ArduinoSerialRpc rpc; void setup() {
    pinMode(2, OUTPUT);
    pinMode(3, OUTPUT);
    rpc.registerArduinoFunction("setLightIntensity", setBrightness);
    }
    
    // Callable method from Java program.
    // Java executes: libraryInstance.executeRemoteFunction("setLightIntensity", 2, 132);
    boolean setBrightness(int pin, int value) {
    if ((pin == 2) || (pin == 3)) {
    analogWrite(pin, value);
    return true;
    } else {
    return false;
    }
    }
    
    Parameters:
    
    functionName - The name of function to call, in Arduino sketch.
    
    arg1 - First value to send.
    
    arg2 - Second value to send.
    
    Returns:
    
    The result of called function;
    
    Throws:
    
    ArduinoRpcJavaFailsException - In any case of communication error or java side problems.
  - executeRemoteFunction
```
public String executeRemoteFunction(String functionName,
                                    String argument)
                             throws ArduinoRpcJavaFailsException
```
    Executes a function (of Arduino sketch) with signature: string functionName(string);
    
    Parameters:
    
    functionName - The name of function to call, in Arduino sketch.
    
    argument - The parameter to send
    
    Returns:
    
    The result of called function
    
    Throws:
    
    ArduinoRpcJavaFailsException - In any case of communication error or java side problems.
  - executeRemoteFunction
```
public float executeRemoteFunction(String functionName,
                                   float argument)
                            throws ArduinoRpcJavaFailsException
```
    Executes a method (of Arduino sketch) with signature: float functionName(float);
    
    Parameters:
    
    functionName - The name of function to call, in Arduino sketch.
    
    argument - The parameter to send
    
    Returns:
    
    The result of called function
    
    Throws:
    
    ArduinoRpcJavaFailsException - In any case of communication error or java side problems
  - handlerReceivingException
```
public void handlerReceivingException(Exception ex)
```
    Overridable function called when an exception occurs during data reads from Arduino.
    
    Parameters:
    
    ex - The occurred exception
  - executeLocalMethod
```
public void executeLocalMethod(String methodToDo)
                        throws ArduinoRpcJavaFailsException
```
    Discovers and executes a method of the extending class.
    
    Parameters:
    
    methodToDo - the name of method to be called
    
    Throws:
    
    ArduinoRpcJavaFailsException - In any case of communication error or java side problems
  - executeLocalMethod
```
public void executeLocalMethod(String methodToDo,
                               int arg1,
                               int arg2)
                        throws ArduinoRpcJavaFailsException
```
    Discovers and executes a method of the extending class.
    
    Parameters:
    
    methodToDo - the name of method to be called
    
    arg1 - the first input parameter
    
    arg2 - the second input parameter
    
    Throws:
    
    ArduinoRpcJavaFailsException - In any case of communication error or java side problems
  - executeLocalMethod
```
public void executeLocalMethod(String methodToDo,
                               String arg)
                        throws ArduinoRpcJavaFailsException
```
    Discovers and executes a method of the extending class.
    
    Parameters:
    
    methodToDo - the name of method to be called
    
    arg - the input parameter
    
    Throws:
    
    ArduinoRpcJavaFailsException - In any case of communication error or java side problems
  - executeLocalMethod
```
public void executeLocalMethod(String methodToDo,
                               float arg)
                        throws ArduinoRpcJavaFailsException
```
    Discovers and executes a method of the extending class.
    
    Parameters:
    
    methodToDo - the name of method to be called
    
    arg - the input parameter
    
    Throws:
    
    ArduinoRpcJavaFailsException - In any case of communication error or java side problems

Class ArduinoJavaSerialRpc

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

MAC_OS_DEFAULT_PORT

RASPBERRY_PI_DEFAULT_PORT

LINUX_DEFAULT_PORT

WINDOWS_DEFAULT_PORT

WINDOWS_USB_1

WINDOWS_USB_2

WINDOWS_USB_3

WINDOWS_USB_4

WINDOWS_USB_5

WINDOWS_USB_6

DATA_RATE_300

DATA_RATE_600

DATA_RATE_1200

DATA_RATE_2400

DATA_RATE_4800

DATA_RATE_9600

DATA_RATE_14400

DATA_RATE_19200

DATA_RATE_28800

DATA_RATE_38400

DATA_RATE_57600

DATA_RATE_115200

Constructor Detail

ArduinoJavaSerialRpc

Method Detail

connect

disconnect

portScanner

getPortName

getBaudRate

getCardName

executeRemoteFunction

executeRemoteFunction

executeRemoteFunction

executeRemoteFunction

handlerReceivingException

executeLocalMethod

executeLocalMethod

executeLocalMethod

executeLocalMethod