[OoB] Controlling Gun Turret with Spring Boot REST Service (Java/Arduino)

• Download source from GitHub

This is the fifth post in my little "Out of Boredom" series dedicated to hobby projects with Arduino. Previous posts were all .NET based:

• [OoB] Moving webcam with joystick and servos (Arduino/SharpDX/WinForms)
• [OoB] Shooting paintball maker with relay, Arduino and .NET WinForms
• [OoB] Sonar with Arduino, C#, JavaScript and HTML5 (Part 2)
• [OoB] Sonar with Arduino, C#, JavaScript and HTML5

Now it's time for a bit of Java!

I will show you how to use Spring Boot framework to quickly create RESTful web service that can receive JSON requests and send commands to Arduino. The aim is to control a servo and relay based gun turret such as this one:

Click here to get an idea of how such turret operates. The video shows a prototype based on ASG pistol. Don't worry, my aim is quite peaceful: I want to build paintball gun turret :)

I will not discuss any electronics setup or Arduino code in this post. Take a look at the articles linked above to see information about PC-Arduino communication, controlling servos and building relay based circuit... I assume that you know what Spring Boot is, but advanced knowledge is not required to follow this post.

Full code of the project is available on GitHub (includes both Java application and Arduino sketch)...

The easiest way to create basic working Spring Boot project is to use Spring Initializr. I started my project by filling the form like this:

Note that Gradle is used to create (fat) Jar package, Java 1.8 is used and the only required dependency is Web. This setup will produce an application running on Tomcat Embedded so there's no need for installing any web server. The app has support for REST controllers so we will be able to handle JSON based communication in a clean way with very little effort...

Without further ado, here is the piece of code responsible for receiving messages from clients:

package springarduino;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class TurretController {
    private final ArduinoConnection arduino;

    @Autowired
    public TurretController(ArduinoConnection arduino) {
        this.arduino = arduino;
    }

    @RequestMapping(value = "turret/execute", 
    method = RequestMethod.POST, consumes = "application/json")
    public TurretResponse executeTurretAction(@RequestBody TurretRequest request) {
        if (request.getPan() < 0 || request.getPan() > 180) {
            throw new IllegalArgumentException
            ("Pan out of 0..180 range (" + request.getPan() + ")");
        }

        if (request.getTilt() < 0 || request.getTilt() > 180) {
            throw new IllegalArgumentException
            ("Tilt out of 0..180 range (" + request.getTilt() + ")");
        }

        boolean sent = arduino.controlTurret(request.getPan(), request.getTilt(), request.isFire());
        if (!sent) {
            throw new RuntimeException("Command not sent :(");
        }

        return new TurretResponse(request.getId(), "Command sent :)");
    }
}

TurretController class has @RestController annotation and a public method marked with @RequestMapping. The mapping specifies that executeTurretAction method should be invoked whenever a client makes a POST request to .../turret/execute URL. Any HTTP client capable of sending POST with Content-Type="application/json" can communicate with such Spring controller method. It can be some desktop application or a simple HTML page with a bit of jQuery for example. I was using Postman Chrome App to prepare requests. In the next post, I will describe how to communicate with such controller from smartphone that runs PhoneGap/AngularJS based application...

executeTurretAction method expects one argument of type TurretRequest:

package springarduino;

public class TurretRequest {
    private int id;
    private int pan;
    private int tilt;
    private boolean fire;

    // public getters and setters hidden for brevity
}

If client sends JSON payload such as this:

{
    "id": "311",
    "pan": "111",
    "tilt": "99",
    "fire": "true"
}

Spring will take care of creating TurretRequest object. Our service method returns TurretResponse:

package springarduino;

public class TurretResponse {
    private int id;
    private String message;

    public TurretResponse(int id, String message) {
        this.id = id;
        this.message = message;
    }

    // public getters and setters hidden for brevity
}

If everything goes well, this kind of data will be sent back to the client:

{
    "id": 19,
    "message": "Command sent :)"
}

You don't have to do anything special to make this happen. Spring chooses HttpMessageConverter implementation to create response in a format that is expected by the client. Another nice feature of our @RestController is the error handling. Let's say that client provides invalid value of tilt angle - this is what is sent back as response:

{
    "timestamp": 1424382893952,
    "status": 500,
    "error": "Internal Server Error",
    "exception": "java.lang.IllegalArgumentException",
    "message": "Tilt out of 0..180 range (222)",
    "path": "/turret/execute"
}

Such message is easy to handle in error callbacks (thanks to 500 HTTP status code) and contains useful properties such as message and exception.

Notice that arduino object of ArduinoConnection type is used inside executeTurretAction method. ArduinoConnecton is a Spring bean responsible for communicating with Arduino over serial port.

Our controller gets reference to proper object thanks to Spring's IoC container. TurretController constructor is annotated with @Autowired so Spring knows that ArduinoConnection objects needs to be injected.

This is the class responsible for talking to Arduino:

package springarduino;

import gnu.io.NRSerialPort;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

import javax.annotation.PostConstruct;
import javax.annotation.PreDestroy;
import java.io.DataOutputStream;

@Component
public class ArduinoConnection {
    private static final int MESSAGE_SEPARATOR = 255;

    private final Logger log = LoggerFactory.getLogger(this.getClass());

    @Value("${arduinoPortName}")
    private String portName;

    @Value("${arduinoBaudRate}")
    private int baudRate;

    private NRSerialPort serial;

    @PostConstruct
    public void connect() {
        log.info("ArduinoConnection PostConstruct callback: connecting to Arduino...");

        serial = new NRSerialPort(portName, baudRate);
        serial.connect();

        if (serial.isConnected()) {
            log.info("Arduino connection opened!");
        }
    }

    @PreDestroy
    public void disconnect() {
        log.info("ArduinoConnection PreDestroy callback: disconnecting from Arduino...");

        if (serial != null && serial.isConnected()) {
            serial.disconnect();

            if (!serial.isConnected()) {
                log.info("Arduino connection closed!");
            }
        }
    }

    public boolean controlTurret(int pan, int tilt, boolean fire){
        try {
            // Actual values sent to Arduino will be in proper unsigned byte range (0..255)
            byte[] message = new byte[]{(byte) pan, (byte) tilt, (byte) (fire ? 1 : 0), (byte) MESSAGE_SEPARATOR};

            DataOutputStream stream = new DataOutputStream(serial.getOutputStream());
            stream.write(message);

            log.info("Turret control message sent (pan={}, tilt={}, fire={})!", pan, tilt, fire);
            return  true;
        } catch (Exception ex) {
            log.error("Error while sending control message: ", ex);
            return false;
        }
    }
}

@Component annotation is there to show Spring that ArduinoConnection is a bean and as such Spring should take care of its lifecycle and usage as dependency. By default, Spring creates beans in singleton scope. This is fine for us - we only need one such object. connect method is marked with @PostConstruct. This makes the method an initialization callback that gets invoked when ArduinoConnection object is created (it will happen when application is started). @PreDestroy is used on disconnect method to make sure that connection to serial port is released when the program is closed.

controlTurret method is the piece of code that is responsible for sending gun turret action request to Arduino. That method is used in TurretController.executeTurretAction, remember? It uses instance of NRSerialPort to communicate over serial port (gnu.io.NRSerialPort package makes it possible). It comes form NeuronRobotics/nrjavaserial library which is a fork of RXTX that greatly simplifies serial port access. nrjavaserial takes care of loading proper native library needed to access the port (it worked well on my Windows 7 x64). As stated before, I'm not going to discuss Arduino communication and microcontroller code in this post. I will just note that you don't have to worry about casting int to byte while message array is created. It's sad but Java doesn't have unsigned bytes so it will show (byte)MESSAGE_SEPARATOR (which is 255) as -1 while debugging, but a correct value will go over wire to Arduino. Take a look at this screen shot from Free Device Monitoring Studio (you can use this tool to check what data is sent to Arduino through serial port):

Let's get back to ArduinoConnection class: portName and baudRate properties are marked with @Value annotations. This way it is very easy to take the settings from configuration file. All you have to do is to create a file named application.properties in /src/main/resources directory and values will be automatically loaded from config. Here's the content of application.properties file: 

server.address = 192.168.0.17
server.port = 8090

arduinoPortName = COM3
arduinoBaudRate = 9600

Apart from aforementioned settings for Arduino, there are two other elements, namely: sever.address and server.port. By default Spring Boot runs the application on localhost:8080. I've changed this to custom settings to make it easy to access the application from devices connected to my WiFi network... Accessing TurretController from such devices is the reason why I added following CorsFilter class to the project:

package springarduino;

import org.springframework.stereotype.Component;

import javax.servlet.*;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

@Component
public class CorsFilter implements Filter {

    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) 
		throws IOException, ServletException {
        HttpServletResponse response = (HttpServletResponse) res;
        response.setHeader("Access-Control-Allow-Origin", "*");
        response.setHeader("Access-Control-Allow-Methods", "POST, GET, OPTIONS");
        response.setHeader("Access-Control-Max-Age", "3600");
        response.setHeader("Access-Control-Allow-Headers", "X-Requested-With");
        chain.doFilter(req, res);
    }

    public void init(FilterConfig filterConfig) {}

    public void destroy() {}
}

Thanks to this Cross-Origin Resource Sharing filter, it's easy to make Ajax calls to executeTurretAction method without using some trickery like JSONP to circumvent same-origin policy restrictions.