How to retrieve an Ardulink 2 Link

In this article we will understand how to retrieve an Ardulink 2 Link instance. In Ardulink 1 a Link instance is retrieved calling a Link static method (getDefaultLink(), createLink(), …) a Link is a concrete class and is composed by a Connection and a Protocol. A Connection can be a Connection on USB or on Bluetooth and so on while a Protocol is a way to serialize messages to or from Arduino into a stream.

In Ardulink 2 a Link is just an interface that defines all the messages that Ardulink can send to Arduino and all the events that Ardulink can catch from Arduino.

There are several ways to retrieve a Link implementation, however the preferred way is the class Links. It’s the preferred way since it will do some stuff around the Link (SRP, single responsibility principle):

Programmers should not use LinkManager nor Configurer expect the have a good reason to do so.

You can retrieve a Link with class Links with:

Link link = Links.getDefault();

but also:

Link link = Links.getLink(URIs.newURI("ardulink://default"));

or:

Link link = Links.getLink(URIs.newURI("ardulink://serial-jssc?port=COM3"));

or in general:

Link link = Links.getLink(URIs.newURI(connectionString));

In the snipet above the connectionString variable contains an URI. It becomes an URI and then a Link instance is retrieved. Links class can retrieve a Link instance using the right URI.

In order to understand better how to set a connectionString let see how a Link can be build.

Link implementations can be build with a LinkFactory that is configured with a LinkConfig. Both LinkFactory and LinkConfig are interfaces too. For each Link implementation there are also a LinkFactory and a LinkConfig implementations that can be found at runtime by other Ardulink classes. This design may seem complex, but it is not for those who want to use a Link.

So if a Link based on JSSC Library is needed the URI will be in the format:

ardulink://serial-jssc?port=COM3&baudrate=9600&pingprobe=false&waitsecs=1

serial-jssc is the Link’s name (defined in the org.ardulink.core.serial.jssc.SerialLinkFactory) while the other values are the specific parameters for a jssc link. Some parameters have a default value while others have a choice list. If you take a look to:

org.ardulink.core.serial.jssc.SerialLinkConfig

you can see for instance:

    @Named("baudrate")
    @Min(1)
    private int baudrate = 115200;

So property named baudrate has a default value equal to 115200.

while:

    @Named("port")
    private String port;


    @ChoiceFor("port")
    public String[] listPorts() {
        return SerialPortList.getPortNames();
    }

So property named port has a choice list retrieved with listPorts method.

In Ardulink 2 you haven’t to call a connect method like Ardulink 1. Link is ready to be used.

link.sendCustomMessage("This is a custom message");

Ardulink can dynamically discover all the Link implementation. It search for files located in META-INF jars folder where the Link Factory name is written down. See for example this file on github for JSSC implementation: org.ardulink.core.linkmanager.LinkFactory

---

As said before, Links class is the preferred way to retrieve a Link instance, however if a programmer needs for some particular features she/he can use other classes.

LinkManager can retrieve a Link instance using a right URI.

Link link = LinkManager.getInstance()
          .getConfigurer(URIs.newURI(connectionString))).newLink();

Configurer is an interface that has some functionalities to manage Link’s properties.

Properties can be specified in the URI or you can specify their values programmatically.

Configurer configurer = connectionManager.getConfigurer(
                     URIs.newURI("ardulink://serial-jssc"));
ConfigAttribute port = configurer.getAttribute("port");
Object aPortValue = port.getChoiceValues()[0];
port.setValue(aPortValue);
Link link = configurer.newLink();

Finally, if you have a project written with Ardulink 1 libraries you can migrate to Ardulink 2 just using another Link. The org.ardulink.legacy.Link class has methods very similar to Ardulink 1 Link methods so you can use this class in your old code.

Link link = Link.createInstance("serial-jssc?port=COM3");
link.sendPowerPinIntensity(13, 200);

This class is deprecated but actually is still used in ardulink-swing module.