Kotlin (and Java)

Creating an AnimationSender

The AnimationSenderFactory object is used to create AnimationSender instances. An AnimationSender is created by calling AnimationSenderFactory.create(). create takes three optional arguments:

• ipAddress: The IP address of the server (defaults to 10.0.0.254)
• port: The port that the client should connect to (defaults to 5)
• connectAttemptLimit: Specify how many times the client should try to connect/reconnect to the server before giving up (defaults to 5)

val sender = AnimationSenderFactory.create(
                 ipAddress = "10.0.0.254",
                 port = 5,
                 connectAttemptLimit = 5
             )

Default AnimationSender

The AnimationSenderFactory object can store a reference to an AnimationSender to use as the default sender if no other sender is specified. This is used by the AnimationData.send() extension function. To specify an AnimationSender as the default sender, call setAsDefaultSender() on that instance.

sender.setAsDefaultSender()

Starting an AnimationSender

Once your AnimationSender has been created by the AnimationSenderFactory, now you have to call that instance's start() method to start the connection. A new coroutine will be created to connect to the server and then listen for messages.

sender.start()

Stopping an AnimationSender

To stop a sender and disconnect it from the server, call the end() method on the AnimationSender instance.

sender.end()

setIPAddress()

The setIPAddress method will first disconnect the sender from the server it is connected to, change the IP address, and then attempt to connect to the server at the new IP.

sender.setIPAddress("10.0.0.254")

Sending Data

There are two ways to send animation data using an AnimationSender. The easiest way is to call the AnimationData.send() extension function also defined in the library. send() takes one optional argument: an AnimationSender which will be used to send the data. If no AnimationSender is specified, send() will use the default sender as specified by the AnimationSenderFactory.

val cc = ColorContainer(0xFF, 0xFF00)
val data = AnimationData().addColor(cc)

data.send()        // Send with default sender
data.send(sender)  // Send with a specified sender

The other way to send data would be to call the AnimationSender's send() method directly, with an AnimationData instance to be sent to the server.

sender.send(data)

AnimationData type notes

The Kotlin/Java library uses the following values for animation, continuous and direction:

• animation: Animation.COLOR, Animation.ALTERNATE, Animation.RIPPLE, etc.
• continuous: null, true, false
• direction: Direction.FORWARD, Direction.BACKWARD

Receiving Data

Received animations are saved to the runningAnimations map and removed when an ENDANIMATION is received for that animation.

In addition, the Kotlin library uses callbacks that run custom lambdas to allow you to specify what to do with data that is received.

OnReceive

The onReceive callback is called whenever the sender receives an AnimationData instance from the server. The AnimationData instance is passed to your callback. Use the onNewAnimation and onEndAnimation callbacks if you want to separate out ENDANIMATIONs from regular animations. Runs before the onNewAnimation and onEndAnimation callbacks.

sender.setOnReceiveCallback { data: AnimationData ->
    // Your code here
}

OnNewAnimation

The onNewAnimation callback is called whenever the sender receives an AnimationData instance from the server whose animation is not ENDANIMATION. The AnimationData instance is passed to your callback. Runs after the onReceive callback.

sender.setOnNewAnimationCallback { data: AnimationData ->
    // Your code here
}

OnEndAnimation

The onEndAnimation callback is called whenever the sender receives an AnimationData instance from the server whose animation is ENDANIMATION. The AnimationData instance is passed to your callback. Runs after the onReceive callback.

sender.setOnEndAnimationCallback { data: AnimationData ->
    // Your code here
}

Other Callbacks

The Kotlin library also includes callbacks for events such as connections or disconnections from the server.

OnConnect

The onConnect callback is called when the sender successfully connects to the server. The IP that you just connected to is passed to your callback as a String.

sender.setOnConnectCallback { ip: String ->
    // Your code here
}

OnDisconnect

The onDisconnect callback is called when the sender loses connection to the server. The IP that just disconnected is passed to your callback as a String.

sender.setOnDisconnectCallback { ip: String ->
    // Your code here
}

Adding the Library to Your Project

Maven Coordinates/Dependency

Use the following dependency to use this library in your project

<dependency>
  <groupId>io.github.animatedledstrip</groupId>
  <artifactId>animatedledstrip-client</artifactId>
  <version>0.5</version>
</dependency>

Snapshots

Development versions of the AnimatedLEDStripClient library are available from the Sonatype snapshot repository:

<repositories>
   <repository>
       <id>sonatype-snapshots</id>
       <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
       <snapshots>
           <enabled>true</enabled>
       </snapshots>
   </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>io.github.animatedledstrip</groupId>
    <artifactId>animatedledstrip-client</artifactId>
    <version>0.6-SNAPSHOT</version>
  </dependency>
</dependencies>

Note About Building

Because we use the dokka plugin to generate our documentation, we must use Java <=9

https://www.oracle.com/technetwork/java/javase/downloads/java-archive-javase9-3934878.html