jodersky / akka-serial

Reactive serial communication library for Akka and Scala.

akka-serial

Serial communication library for Scala, designed to be reactive, lightweight and easily integrable with Akka applications. See the website for a guide.

Highlights

• Reactive: only does work when required (no constant polling of ports or blocking IO)
• Integrates seamlessly with Akka
• Portable to POSIX systems
• Watchable ports: react to connection of new device
• Compatible with Reactive Streams

Native side

Since hardware is involved in serial communication, a Scala-only solution is not possible. Nevertheless, the native code is kept simple and minimalistic with the burden of dealing with threads left to Scala. The code aims to be POSIX compliant and therefore easily portable.

Directory Structure

akka-serial/
├── Documentation         Sources for user documentation as published on the website.
├── core                  Main Scala source files.
├── dev                   Firmware samples for serial devices, to make testing easier.
├── native                C sources used to implement serial communication.
│   └── lib_native        Compiled native libraries that are published in the fat jar.
├── project               Build configuration.
├── samples               Runnable example projects.
├── stream                Stream API, used to connect with Akka streams.
└── sync                  Synchronous, non-Akka-dependent code.

Website source code is in the git branch 'gh-pages'.

Build

Detailed documentation on building akka-serial is available on the website (or, equivalently, in developer.md).

Since akka-serial integrates into the Akka-IO framework, a good resource on its general design is the framework's documentation.

This project is also an experiment on working with JNI and automating build infrastructure.

Copying

akka-serial is released under the terms of the 3-clause BSD license. See LICENSE for details.

Notes

This project used to be called "flow". It was renamed to "akka-serial".

akka-serial's Issues

Add options to streaming sample

Connection settings are currently hard-coded in the terminal-stream sample. For a better "it just works out of the box experience", it would be nice to interactively set connection options as is done in the plain terminal sample.

java.lang.NoSuchMethodError on Java 8

Release 4.2.0 is broken on Java 8, it fails with this error:

java.lang.NoSuchMethodError: java.nio.ByteBuffer.clear()Ljava/nio/ByteBuffer;
 	at akka.serial.SerialOperator$Reader$.loop(SerialOperator.scala:25)
 	at akka.serial.SerialOperator$Reader$.run(SerialOperator.scala:43)

The reason is a breaking change in Java 9+ that akka-serial 4.2.0 was built on.
The problem is described nicely here: https://jira.mongodb.org/browse/JAVA-2559

Other projects have (had) the same problem, e.g. lmdbjava:
lmdbjava/lmdbjava#117

Bootsrapping is broken

The m4 (autotools) script ax_jni_include_dir.m4 which searches for jni header files is ignored. Bootstrapping the native build no longer works.

Issue is described in #21

publish 2.2.2

What I get when I try to resolve it

[warn]     ::::::::::::::::::::::::::::::::::::::::::::::
[warn]     ::          UNRESOLVED DEPENDENCIES         ::
[warn]     ::::::::::::::::::::::::::::::::::::::::::::::
[warn]     :: com.github.jodersky#flow_2.11;2.2.2: not found
[warn]     ::::::::::::::::::::::::::::::::::::::::::::::

Use CI

Use a continuous integration mechanism to avoid build issues (as shown by #26).

Move native build tool to CMake

Autotools is arcane and also requires a two-step process to build (./bootstrap and then the usual ./configure && make). Using CMake will ease the build process by making it stateless and is especially useful for CI.

Since flow requires a jdk to run anyway, it is safe to assume that it will only be built on relatively new platforms that support cmake.

Fails to compile on fedora 20

Cloned the current repository and run sbt test

Fails on both jdk1.7.0_60 and jdk1.8.0_05, Linux 64 bit Fedora 20.
Essentially the same failure if I drop the scala version back to 2.11.0.

[error] 
[error]      while compiling: /home/rsearle/work/flow/flow/src/main/scala/com/github/jodersky/flow/Serial.scala
[error]         during phase: typer
[error]      library version: version 2.10.3-20130923-e2fec6b28dfd73482945ffab85d9b582d0cb9f17
[error]     compiler version: version 2.10.3-20130923-e2fec6b28dfd73482945ffab85d9b582d0cb9f17
[error]   reconstructed args: -classpath /home/rsearle/work/flow/flow/target/scala-2.11/classes:/home/rsearle/.ivy2/cache/com.typesafe.akka/akka-actor_2.11/jars/akka-actor_2.11-2.3.3.jar:/home/rsearle/.ivy2/cache/com.typesafe/config/bundles/config-1.2.1.jar:/home/rsearle/.ivy2/cache/com.github.scala-incubator.io/scala-io-core_2.11/jars/scala-io-core_2.11-0.4.3.jar:/home/rsearle/.ivy2/cache/org.scala-lang.modules/scala-parser-combinators_2.11/bundles/scala-parser-combinators_2.11-1.0.1.jar:/home/rsearle/.ivy2/cache/com.madgag/scala-arm_2.11/jars/scala-arm_2.11-1.3.3.jar:/home/rsearle/.ivy2/cache/org.scala-lang.plugins/scala-continuations-library_2.11/bundles/scala-continuations-library_2.11-1.0.1.jar:/home/rsearle/.ivy2/cache/com.github.scala-incubator.io/scala-io-file_2.11/jars/scala-io-file_2.11-0.4.3.jar -deprecation -feature -unchecked -bootclasspath /usr/java/jdk1.8.0_05/jre/lib/resources.jar:/usr/java/jdk1.8.0_05/jre/lib/rt.jar:/usr/java/jdk1.8.0_05/jre/lib/sunrsasign.jar:/usr/java/jdk1.8.0_05/jre/lib/jsse.jar:/usr/java/jdk1.8.0_05/jre/lib/jce.jar:/usr/java/jdk1.8.0_05/jre/lib/charsets.jar:/usr/java/jdk1.8.0_05/jre/lib/jfr.jar:/usr/java/jdk1.8.0_05/jre/classes:/home/rsearle/.ivy2/cache/org.scala-lang/scala-library/jars/scala-library-2.11.1.jar
[error] 
[error]   last tree to typer: Literal(Constant(()))
[error]               symbol: null
[error]    symbol definition: null
[error]                  tpe: Unit
[error]        symbol owners: 
[error]       context owners: object CommandFailed -> object Serial -> package flow
[error] 
[error] == Enclosing template or block ==
[error] 
[error] ModuleDef( // object CommandFailed in object Serial
[error]   <module> <synthetic>
[error]   "CommandFailed"
[error]   Template(
[error]     runtime.this.AbstractFunction2[Command, Throwable, CommandFailed] // parents
[error]     ValDef(
[error]       private
[error]       "_"
[error]       <tpt>
[error]       <empty>
[error]     )
[error]     // 2 statements
[error]     DefDef( // def <init>: <?> in object CommandFailed
[error]       <method>
[error]       "<init>"
[error]       []
[error]       List(Nil)
[error]       <tpt>
[error]       Block(
[error]         Apply(
[error]           super."<init>"
[error]           Nil
[error]         )
[error]         ()
[error]       )
[error]     )
[error]     DefDef( // final override def toString: <?> in object CommandFailed
[error]       <method> final override <synthetic>
[error]       "toString"
[error]       []
[error]       List(Nil)
[error]       <tpt>
[error]       "CommandFailed"
[error]     )
[error]   )
[error] )
[error] 
[error] == Expanded type of tree ==
[error] 
[error] TypeRef(TypeSymbol(final abstract class Unit extends AnyVal))
[error] 
[error] uncaught exception during compilation: scala.reflect.internal.MissingRequirementError
[trace] Stack trace suppressed: run last flow/compile:compile for the full output.
[error] (flow/compile:compile) scala.reflect.internal.MissingRequirementError: class scala.annotation.serializable in compiler mirror not found.
[error] Total time: 4 s, completed May 31, 2014 1:20:11 PM

SBT Native Compilation on Mac

I guess I had similar problems earlier, but I did not continue solving it the last time and I'm now in the process of using flow for one of my projects and I just checked out the source code and followed the documentation

http://www.jodersky.ch/flow/documentation/3.0/developer - Creating a fat jar

I get the following error:

jothi@Joesans-MacBook-Pro ~/P/P/flow> sbt native/package
[info] Loading project definition from /Users/jothi/Projects/Personal/flow/project
[info] Set current project to root (in build file:/Users/jothi/Projects/Personal/flow/)
[info] Building library with native build tool CMake
Exception in thread "Thread-9" java.io.IOException: Cannot run program "cmake" (in directory "/Users/jothi/Projects/Personal/flow/flow-native/target/native/x86_64-darwin/build"): error=2, No such file or directory
at java.lang.ProcessBuilder.start(ProcessBuilder.java:1048)
at sbt.SimpleProcessBuilder.run(ProcessImpl.scala:349)
at sbt.SequentialProcess.runAndExitValue(ProcessImpl.scala:240)
at sbt.CompoundProcess$$anonfun$1.apply$mcV$sp(ProcessImpl.scala:201)
at sbt.Spawn$$anon$3.run(ProcessImpl.scala:17)
Caused by: java.io.IOException: error=2, No such file or directory
at java.lang.UNIXProcess.forkAndExec(Native Method)
at java.lang.UNIXProcess.(UNIXProcess.java:248)
at java.lang.ProcessImpl.start(ProcessImpl.java:134)
at java.lang.ProcessBuilder.start(ProcessBuilder.java:1029)
... 4 more
Exception in thread "Thread-8" java.lang.RuntimeException: No exit code: process destroyed.
at scala.sys.package$.error(package.scala:27)
at sbt.CompoundProcess$$anonfun$exitValue$1.apply(ProcessImpl.scala:193)
at sbt.CompoundProcess$$anonfun$exitValue$1.apply(ProcessImpl.scala:193)
at scala.Option.getOrElse(Option.scala:120)
at sbt.CompoundProcess.exitValue(ProcessImpl.scala:193)
at sbt.SequentialProcess$$anonfun$runAndExitValue$1.apply$mcI$sp(ProcessImpl.scala:241)
at sbt.SequentialProcess$$anonfun$runAndExitValue$1.apply(ProcessImpl.scala:241)
at sbt.SequentialProcess$$anonfun$runAndExitValue$1.apply(ProcessImpl.scala:241)
at sbt.CompoundProcess.runInterruptible(ProcessImpl.scala:214)
at sbt.SequentialProcess.runAndExitValue(ProcessImpl.scala:241)
at sbt.CompoundProcess$$anonfun$1.apply$mcV$sp(ProcessImpl.scala:201)
at sbt.Spawn$$anon$3.run(ProcessImpl.scala:17)

I guess that I need to have Make installed on my Mac?

Any ideas?

Error while building

I'm trying to follow through the documentation to build the project and I git the following error. I'm at the top folder when I issued the sbt command. Here is the error that I get!

My-MacBook-Pro:flow joe$ sbt flow/packageBin
Java HotSpot(TM) 64-Bit Server VM warning: ignoring option MaxPermSize=724M; support was removed in 8.0
[info] Loading project definition from /Projects/flow/project
[info] Set current project to root (in build file:/Projects/flow/)
[error] Expected ID character
[error] Not a valid command: flow (similar: loadp)
[error] Expected project ID
[error] Expected configuration
[error] Expected ':' (if selecting a configuration)
[error] Expected key
[error] Not a valid key: flow (similar: fork)
[error] flow/packageBin
[error] ^
My-MacBook-Pro:flow joe$

Any clues?

Does the provided arm binaries support the Raspberry Pi?

I would like to know whether it is possible to run this package on a Raspberry Pi. I know that you have specifically mentioned the binaries provided are for armv7l, and the RPi is armv6, but given that Raspbian has hardfloat support is there any chance of using the provided binaries. If not could you please provide basic compilation steps for ARM and whether it is possible cross-compile the package on a PC.
Thanks,
Tanaka

Any plans to support 2.11.1?

Hi!

Do you have any plans for support the latest version of Scala? Are there any roadblocks other than updating the build? :)

Thanks,

Chip

any guidance how to make it work for windows?

A friend of mine has to demostrate spectophotometer gui for windows but I am not sure what exactly I should do to make it work for windows. I can try to install windows32 to VM and try to build native libs inside VM but it will be very time consuming for me. Maybe you already have prebuild binaries for windows 32 and windows 64 to download/install?

RTS & DTR

The library does not seems to implement those commands.
Is there a way to send them? Am I missing something?

Thanks in advance.

Adding a Timeout if the Serial Port does not respond

Could this be added to the implementation? I would need a Timeout message after writing bytes to the opened serial port where I can specify after a certain FiniteDuration, the read should Timeout? I have a scenario where I have two devices and I try to connect to these two devices one after the other. If the first one does not respond after a certain time (which I currently have in my Actor), I try the next one. Could this be added to the IO(Serial) actor such that it handles this internally in the library itself, rather than me controlling it from outside?

I can post you an example tomorrow.

Native Serial failure on Maveric

I'm runinning a Mac OSX mavericks based system and have plugged in a USB to serial cable which I have connected to a board. I'm using your library to open the serial port which shows up as /dev/cu.usbserial-FTH0YJ3G. Opening the port fails with an exception
java.lang.UnsupportedClassVersionError: com/github/jodersky/flow/internal/NativeSerial : Unsupported major.minor version 51.0

I've uploaded my project on github

I'd really like to use your library so any help would be appreciated.

Cannot extract native binary on ARM

Using the native fat jar on an ARM platform throws an exception:

java.lang.UnsatisfiedLinkError: Cannot extract flow's native library,
the native library may not exist for your specific architecture/OS combination.

This is a packaging bug. Versions of flow-native from 2.0.9 to 2.1.1 distributed on maven are affected. Self-compiled binaries should not have this issue.

Reported by @slouc via email

Add support for Windows

This is a community issue, anyone is welcome to pick it up.

Flow's native libary is written in C and aims to be portable by only using the standard POSIX API. However, since Windows does not provide support for the API, flow currently cannot be compiled for it.
Resolving this issue would require an additional native implementation, similar to the current posix one.

A potential starting point is provided here. Essentially, all that is required is an implementation of flow.h.

Please feel free to comment here or ask on the chat. Any help on providing Windows support out-of-the-box is greatly appreciated!

Watching Events on Port

How can I implement a "Watch" for specific events on a port? For example I want to get a message if the CTS line has changed state.

Unable to use Flow 2.4.0-M2 (unreleased dependency?)

It seems I'm unable to use Flow 2.4.0-M2 in my SBT-based project. When I try sbt assembly, I get:

[warn]  module not found: ch.jodersky#jni-library_2.11;0.2-SNAPSHOT
[warn] ==== local: tried
[warn]   /Users/maarten/.ivy2/local/ch.jodersky/jni-library_2.11/0.2-SNAPSHOT/ivys/ivy.xml
[warn] ==== jcenter: tried
[warn]   https://jcenter.bintray.com/ch/jodersky/jni-library_2.11/0.2-SNAPSHOT/jni-library_2.11-0.2-SNAPSHOT.pom
[warn] ==== public: tried
[warn]   https://repo1.maven.org/maven2/ch/jodersky/jni-library_2.11/0.2-SNAPSHOT/jni-library_2.11-0.2-SNAPSHOT.pom
[info] Resolving jline#jline;2.12.1 ...
[warn]  ::::::::::::::::::::::::::::::::::::::::::::::
[warn]  ::          UNRESOLVED DEPENDENCIES         ::
[warn]  ::::::::::::::::::::::::::::::::::::::::::::::
[warn]  :: ch.jodersky#jni-library_2.11;0.2-SNAPSHOT: not found
[warn]  ::::::::::::::::::::::::::::::::::::::::::::::
[warn] 
[warn]  Note: Unresolved dependencies path:
[warn]      ch.jodersky:jni-library_2.11:0.2-SNAPSHOT
[warn]        +- com.github.jodersky:flow_2.11:2.4.0-M2 (/Users/maarten/Projects/hyperion/build.sbt#L59)
[warn]        +- hyperion:hyperion-meter-agent_2.11:1.0.0-SNAPSHOT

My first guess that it's due to using a non-released version of jni-library...

ARMv6 support disappeared

I'm trying to upgrade my app (currently on flow 2.4.1) to the latest version of akka-serial.

I noticed that native/lib_native/ doesn't contain a folder called armv6l-linux, so I first built the terminal sample and tried to run it:

Exception in thread "main" java.lang.UnsatisfiedLinkError: Native library libakkaserial1.so (/native/armv6l-linux/libakkaserial1.so) cannot be found on the classpath.
	at akka.serial.sync.UnsafeSerial$.loadPackaged$1(UnsafeSerial.scala:20)
	at akka.serial.sync.UnsafeSerial$.load$1(UnsafeSerial.scala:20)
	at akka.serial.sync.UnsafeSerial$.<init>(UnsafeSerial.scala:20)
	at akka.serial.sync.UnsafeSerial$.<clinit>(UnsafeSerial.scala)
	at akka.serial.Serial$.debug(Serial.scala:136)

I've built a binary for armv6l-linux, put it in src/main/resources/native and re-packaged the sample. Now it outputs:

[INFO] [09/10/2017 12:58:36.848] [akka-serial-akka.actor.default-dispatcher-2] [akka://akka-serial/user/terminal] Requesting manager to open port: /dev/ttyUSB0, baud: 115200
Error acquiring lock on port: 11
[ERROR] [09/10/2017 12:58:37.288] [akka-serial-akka.actor.default-dispatcher-3] [akka://akka-serial/user/terminal] Connection failed, stopping terminal. Reason: akka.serial.PortInUseException: 

Which is expected since another process is using the port at the same time.

I think it would be nice to have armv6 support (see also #21). There is a work-around (by packaging the .so with my app) but it's not very elegant IMHO.

I can contribute the .so for armv6 either by e-mail (as I did for #21) or as a pull request. What would be your preferred method?

change C code to scala-native

In a longterm it would be nice to see scala-native instead of C code.

Issue when Building Native library on Mac OS X with JDK 1.8

When trying to do a

sh ./bootstrap

I get the following error:

./bootstrap: line 3: autoreconf: command not found

Add Akka-Stream support

Can we have Source, Sink or even Flow based on IO(Serial)?

Tests don't run on MacOS

The socat available via homebrew on the mac doesn't support setting the baudrate via the b115200 flag, which makes all tests fail with an error like this:

parseopts(): unknown option "b115200"

The work around is a s/b115200/ispeed=115200,ospeed=115200/ across the whole codebase (two locations). With that in place everything works nicely.

Probably the tests should test for the current platform and then use either b115200 (Linux) or ispeed=115200,ospeed=115200 (macOS).

permission problems

I develop a GUI for openhardware spectophotometer ( https://github.com/antonkulaga/di-lambda ) and I use flow to connect to it via USB serial port. I experience a lot of problems.
The most unpleasant one is a permission problem. Linux users have to add themselves to special groups to be able to access the serial port. And even after addition some errors occur, for instance when you pluged in the device and then suddengly pluged it out then after pluging it back you will have a permission problem even if you already added yourself to right groups. And sometimes such permission problems appear even when I restarted the app (probably native lib part of the flow is still active)

Provide ARM binaries that can run on the Raspberry Pi

Following #1, I've checked to see if the shipped binaries run on the Raspberry Pi. They do not, and the JVM crashes because of that. I was able to compile the native code for ARMv6 on the Pi, and run my application with that binary.

It would be great to see a version of flow that supports the Pi out-of-the-box. Would that be possible? Is there a way I could contribute?

Data not being received without external interference

I've been using flow 1.2.0 for a project on a BeagleBone Black(http://beagleboard.org/Products/BeagleBone%20Black), which means I'm using the ARM version of the native lib, but I've run into a issue with receiving data.
It seems as if data is never received, even though it has been confirmed that there is indeed data on the physical connection. If I open the port in minicom I see data being received, and furthermore if I open the settings dialog in minicom and change a, seemingly, random setting, my application using flow begins receiving the correct data.

I'm not sure if this is a problem with the native or scala code, I'll be looking into this and report back with any findings.

Testing Mocks

Add some examples on how to create some testing mock for serial port..
For now I'm using (for local testing) socat:

# sudo socat -d -d pty,link=/dev/master,raw,echo=0,user=gook,group=staff  pty,link=/dev/slave,raw,echo=0,user=gook,group=staff

then I connect "terminal-sample" to the port /dev/master - and anything that is send to the /dev/slave got delivered to application..

would be nice get some examples on how to use that (or some other solution) for integration / unit testing, or/and how to crate mocks for Lib

Serial has happened a problem,why?

when I use you dependecy,
I want to connect Serial port：COM2 to read and write;
I use java like this:

    final ActorSystem system = ActorSystem.create("serial");
    final ActorRef watcher = system.actorOf(Props.create(SerialWatch.class), "watcher");
    final Enumeration.Value parity = Parity.None();
    SerialSettings ss=new SerialSettings(38400,8,false,parity);
    final Serial.Open port = new Serial.Open("COM2", ss, 320);
    final ActorRef serialActor = Serial.get(system).manager();
    serialActor.tell(port,watcher);

and then have exception:
Uncaught error from thread [serial-akka.actor.default-dispatcher-2]: null, shutting down JVM since 'akka.jvm-exit-on-fatal-error' is enabled for ActorSystem[serial]
java.lang.ExceptionInInitializerError: null
at akka.serial.sync.SerialConnection$.open(SerialConnection.scala:132)
at akka.serial.SerialManager$$anonfun$receive$1.$anonfun$applyOrElse$1(SerialManager.scala:27)
at scala.util.Try$.apply(Try.scala:209)
at akka.serial.SerialManager$$anonfun$receive$1.applyOrElse(SerialManager.scala:27)
at akka.actor.Actor.aroundReceive(Actor.scala:517)
at akka.actor.Actor.aroundReceive$(Actor.scala:515)
at akka.serial.SerialManager.aroundReceive(SerialManager.scala:13)
at akka.actor.ActorCell.receiveMessage(ActorCell.scala:588)
at akka.actor.ActorCell.invoke(ActorCell.scala:557)
at akka.dispatch.Mailbox.processMailbox(Mailbox.scala:258)
at akka.dispatch.Mailbox.run(Mailbox.scala:225)
at akka.dispatch.Mailbox.exec(Mailbox.scala:235)
at akka.dispatch.forkjoin.ForkJoinTask.doExec(ForkJoinTask.java:260)
at akka.dispatch.forkjoin.ForkJoinPool$WorkQueue.runTask(ForkJoinPool.java:1339)
at akka.dispatch.forkjoin.ForkJoinPool.runWorker(ForkJoinPool.java:1979)
at akka.dispatch.forkjoin.ForkJoinWorkerThread.run(ForkJoinWorkerThread.java:107)
Caused by: java.lang.RuntimeException: Error running uname command
at scala.sys.package$.error(package.scala:27)
at akka.serial.sync.UnsafeSerial$.liftedTree1$1(UnsafeSerial.scala:20)
at akka.serial.sync.UnsafeSerial$.loadPackaged$1(UnsafeSerial.scala:20)
at akka.serial.sync.UnsafeSerial$.load$1(UnsafeSerial.scala:20)
at akka.serial.sync.UnsafeSerial$.(UnsafeSerial.scala:20)
at akka.serial.sync.UnsafeSerial$.(UnsafeSerial.scala)
... 16 common frames omitted

Resolution issues

The latest release, v2.5.0-M1 has resolution issues and will not build unless sbt-jni is published locally.

latest versions not in maven central ?

hum, I can not find last version in maven central, in which repository is it available ?

http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.github.jodersky%22%20