Spacecode SDK - Annotated Samples

Annotated Samples - Java
This page presents implementations of the Java SDK. These lasts are voluntarily verbose and should be considered as an extension of the documentation.

Java SDK - v1.2

Find Local Devices

Find Local Devices
Local devices can be connected using their serial number and/or a serial port name. When none of these parameters are available, the SDK allows scanning the serial ports to find Smart Devices plugged to the computer.
The following Regular Expressions are used to find Serial Ports on the present computer and detect Smart Devices.
```
// GNU/Linux, in folder /dev/.
"(ttyS|ttyUSB|ttyACM|ttyAMA|rfcomm|ttyO)[0-9]{1,3}"
// Solaris, in folder /dev/term/.
"[0-9]*|[a-z]*"
// Mac OS X, folder /dev/.
"tty.(serial|usbserial|usbmodem).*"

// Windows: use Windows API to find available serial ports...
```

public class FindLocalDevices
{
    public static void main(String[] args)
    {

Here localDevices is used to store the instances of Device found by the SDK, using the static method getPluggedDevices. If no device is available, pluggedDevices references an empty Map.
```
        List<Device> localDevices = new ArrayList<>();

        // get all local devices available
        Map<String, PluggedDevice> pluggedDevices = Device.getPluggedDevices();
```

        if(pluggedDevices.isEmpty())
        {
            out.println("No device available. End.");
            return;
        }

Display the information provided by the class PluggedDevice.

        for(PluggedDevice pd : pluggedDevices.values())
        {
            // display: "DeviceType (SerialNumber) on port PortName"
            out.println(
                    String.format("%s (%s) on port %s ",
                    pd.getDeviceType(),
                    pd.getSerialNumber(),
                    pd.getSerialPort()
                )
            );

Try to create and connect all devices found. If any instantiation fails, a DeviceCreationException is thrown.
An Event Listener (or Handler) is added to each device (see the implementation SampleEventHandler below).

            try {
                Device newDevice = new Device(pd.getSerialNumber(), pd.getSerialPort());
                localDevices.add(newDevice);
                newDevice.addListener(new SampleEventHandler(newDevice));
            } catch (DeviceCreationException dce) {
                // catch DeviceCreationException to know if the device could not be initialized
                err.println(
                    String.format(
                        "(Unable to connect with this device : %s)", 
                        dce.getMessage()
                    )
                );
            }
        }

Finally release all devices. Calling the method release is highly recommended, as it allows properly freeing the memory and closing the connection to the serial port.
```
        // release all connected devices
        for(Device device : localDevices)
        {
            device.release();
        }
    }    
```

BasicEventHandler handles the (very) basic events: the SDK provides many other types of events handlers.
The instance of Device to be listened is passed as a parameter, as it can be useful in the event methods.

    // The event listener is an inner static class for this example
    private static class SampleEventHandler implements BasicEventHandler
    {
        private Device _device;
    
        SampleEventHandler(Device device)
        {
            _device = device;
        }

Notify the disconnection of the device. This event is raised when the device has been unplugged (local devices), or the connection with the RFID board has been lost (extremely rare failure).

        @Override
        public void deviceDisconnected()
        {
            out.println(
                String.format("Device %s has been disconnected.", _device.getSerialNumber())
            );
        }

Notify any change in the device status (Scanning, Lighting LED's, Door Open, ...).

        @Override
        public void deviceStatusChanged(DeviceStatus deviceStatus)
        {
            out.println(
                String.format("Device %s -> [%s].",
                    _device.getSerialNumber(),
                    deviceStatus
                )
            );
        }
    }
}

Scan and Light tags

Scan and Light tags
In this example, the class contains more than one method using the instance of Device, which consequently cannot be a local variable.
```
public class ScanLightTags
{
    private static Device _smartboard;

    public static void main(String[] args)
    {
```
The serial number of the SmartBoard is unknown at this stage, but the system provides tools which allow finding the serial port attached to the device (/dev/ttyUSB0).
Note: Using a remote device is perfectly transparent, simply use new TcpDevice(ip); instead.
```
        try  {
            _smartboard = new Device(null, "/dev/ttyUSB0");
        } catch (DeviceCreationException dce) {
            err.println("Unable to connect the SmartBoard.");
            return;
        }
```
Add an event listener (see the class below) to handle scan and lighting events.
```
        _smartboard.addListener(new SampleEventHandler(_smartboard));
```
Request a scan and voluntarily block the main thread on a Scanner input. The rest of the program will be processed in the event handler.
At this stage, if the user ends the program, the local device is released and stop any task in progress.
Note: Calling the method stopLightingTagsLed is not required before release if a local device is used. However, with a remote device, release only closes the TCP socket and would not stop the lighting process.
```
        _smartboard.requestScan();
        out.println("Scan requested, waiting for events.");
    
        // wait for an input before releasing the device and exiting
        out.println("Press Enter to exit...");
        new Scanner(System.in).nextLine();

        _smartboard.stopLightingTagsLed();
        _smartboard.release();
    }
```
Called when the event scanCompleted is raised (see Interface ScanEventHandler). The result of the scan (an instance of Inventory) is available using the method getLastInventory. All the tags scanned are then passed to the method startLightingTagsLed.
Note: startLightingTagsLed blocks the current thread until the device finished looking for the tags to be lighted. It is highly recommended not to start this operation in the event thread.
```
    private static void onScanCompleted()
    {
        // Warning: getLastInventory() may return null if using a TcpDevice
        List<String> tags = _smartboard.getLastInventory().getTagsAll();
    
        out.println(String.format("Scan Completed: %d tags scanned.", tags.size()));
    
        _smartboard.startLightingTagsLed(tags);
    }
```

Called when the event lightingStarted is raised (see Interface LedEventHandler). The event comes with the list of UID's of the tags not found or not lighted.

    private static void onLightingStarted(List<String> tagsNotLighted)
    {
        out.println("Lighting Started!");
    
        for(String uid : tagsNotLighted)
        {
            err.println(String.format("%s not lighted", uid));
        }
    }

SampleEventHandler additionally implements ScanEventHandler and LedEventHandler.

    private static class SampleEventHandler implements ScanEventHandler, LedEventHandler
    {

Implements scanCompleted. The code has been put in the method onScanCompleted for a better readability.

        @Override
        public void scanCompleted()
        {
            onScanCompleted();
        }

Implements lightingStarted. The code has been put in the method onLightingStarted for a better readability.

        @Override
        public void lightingStarted(List<String> tagsNotLighted)
        {
            onLightingStarted(tagsNotLighted);
        }

        // Note: Irrelevant implementations are hidden for clarity reasons
    }
}

Continuous Scanning

Continuous Scanning
In this example, the class contains more than one method using the instance of Device, which consequently cannot be a local variable.
```
public class ContinuousScanning
{
    private static Device _smartboard;

    public static void main(String[] args)
    {
```
The serial number of the SmartBoard is unknown at this stage, but the system provides tools which allow finding the serial port attached to the device (/dev/ttyUSB0).
Note: Using a remote device is perfectly transparent, simply use new TcpDevice(ip); instead.
```
        try  {
            _smartboard = new Device(null, "/dev/ttyUSB0");
        } catch (DeviceCreationException dce) {
            err.println("Unable to connect the SmartBoard.");
            return;
        }
```

Add an event listener (see the class below) to handle scan events.

        _smartboard.addListener(new SampleEventHandler(_smartboard));

Request a scan and voluntarily block the main thread on a Scanner input. The rest of the program will be processed in the event handler.
At this stage, if the user ends the program, the local device is released and stop any task in progress.
```
        _smartboard.requestScan();
    
        // wait for an input before releasing the device and exiting
        new Scanner(System.in).nextLine();
        _smartboard.release();
    }
```

Called when the event scanCompleted is raised (see Interface ScanEventHandler). The result of the scan (an instance of Inventory) is available using the method getLastInventory.
As soon as the scan is completed, display the number of tags Added, already Present and Removed from the device, and ask the device to start scanning again.

    private static void onScanCompleted()
    {
        // Warning: With Remote Devices, "getLastInventory" result can be null
        Inventory inventory = _smartboard.getLastInventory();
    
        out.println(String.format("Scan Completed at %s", inventory.getCreationDate()));
        out.println(String.format("%d tags added", inventory.getNumberAdded()));
        out.println(String.format("%d tags already present", inventory.getNumberPresent()));
        out.println(String.format("%d tags removed", inventory.getNumberRemoved()));
    
        _smartboard.requestScan();
    }

Called when the events scanFailed or scanCancelledByHost are raised (see Interface ScanEventHandler).

    private static void onScanCancelledOrFailed()
    {
        err.println("Scan cancelled or failed.");
        _smartboard.requestScan();
    }

SampleEventHandler additionally implements ScanEventHandler.

    private static class SampleEventHandler implements ScanEventHandler
    {

Implements scanCompleted. The code has been put in the method onScanCompleted for a better readability.

        @Override
        public void scanCompleted()
        {
            onScanCompleted();
        }

Implements scanFailed and scanCancelledByHost(). The code has been put in the method onScanCancelledOrFailed for a better readability.

        @Override
        public void scanFailed()
        {
            onScanCancelledOrFailed();
        }
    
        @Override
        public void scanCancelledByHost()
        {
            onScanCancelledOrFailed();
        }

        // Note: Irrelevant implementations are hidden for clarity reasons
    }
}

Annotated Samples - Java

Find Local Devices

Find Local Devices

Scan and Light tags

Scan and Light tags

Continuous Scanning

Continuous Scanning