improve READMEs

Author: JonasVautherin

README.md

@@ -4,16 +4,19 @@ This is the Java frontend implementation to [MAVSDK](https://github.com/mavlink/
 
 It is organized as follows:
 
-* The [sdk](./sdk) directory contains the different components provided by this project.
 * The [examples](./examples) directory contains Java and Android examples using the sdk.
+* The [sdk](./sdk) directory contains the actual SDK.
 
-## Contributing
+Detailed instructions on how to run the examples and how to build the SDK are available in
+those directories.
 
-Please read the "Contributing" section of the specific project you are interested in.
+## QuickStart
+
+The fastest way to start is to follow the instructions in the README of the [java-client](./examples/java-client) example.
 
 ## Coding style
 
-Java/Android coding style is ensured using CheckStyle with the Google configurations.
+Java/Android coding style is ensured using CheckStyle with the Google style.
 
 ### Command line
 

examples/java-client/README.md

@@ -1,13 +1,27 @@
+# Java client
+
+This project is meant to show examples using MAVSDK-Java, and is a good place to get started.
+
 ## Prerequisites
 
-The examples include MAVSDK-Java using gradle, but `protoc-gen-dcsdk` must be in your PATH. It requires Python 3.6+ and can be built from `sdk/proto/pb_plugins` by running:
+MAVSDK-Java will connect to a running instance of `mavsdk_server`, that can be downloaded from the [MAVSDK release page](https://github.com/mavlink/MAVSDK/releases).
+
+Running `mavsdk_server` from the command line will show output similar to the following:
 
-```sh
-pip install -r requirements.txt
-pip install -e .
 ```
+$ ./mavsdk_server
+[02:58:29|Info ] MAVSDK version: 0.18.3-51-g0c2c48f1 (mavsdk_impl.cpp:25)
+[02:58:29|Debug] New: System ID: 0 Comp ID: 0 (mavsdk_impl.cpp:361)
+[02:58:29|Info ] Server set to listen on 0.0.0.0:50051 (grpc_server.cpp:44)
+[02:58:29|Info ] Server started (grpc_server.cpp:28)
+[02:58:29|Info ] Waiting to discover system... (connection_initiator.h:58)
+```
+
+The other requirement is to have a MAVLink drone (or simulator) running. You can get started with the simulation environment [here](https://dev.px4.io/master/en/simulation/). If using docker, an alternative is to run a headless gazebo instance, as described [here](https://github.com/JonasVautherin/px4-gazebo-headless):
 
-Make sure to add `protoc-gen-dcsdk` to your PATH, and try to run the examples!
+```sh
+$ docker run --rm -it jonasvautherin/px4-gazebo-headless:v1.9.2
+```
 
 ## Running the examples
 
@@ -19,6 +33,36 @@ The examples can be run with the following commands:
 ./gradlew runMission
 ```
 
-The examples will connect to a running `mavsdk_server` instance. The `mavsdk_server` binary can be downloaded from the [MAVSDK release page](https://github.com/mavlink/mavsdk/releases).
-
 Note that running `./gradlew run` will default to `takeoffAndLand`.
+
+## Playing with jshell, the Java REPL
+
+It can be useful to start with the REPL to get a feeling of how MAVSDK-Java works. Try to start jshell from gradle (note: that may not work on all platforms):
+
+```sh
+./gradlew jshell
+```
+
+If everything goes well, you should now be in an interactive jshell, showing the prompt:
+
+```
+jshell>
+```
+
+Let's start by importing the `Action` plugin:
+
+```
+jshell> import io.mavsdk.action.Action
+```
+
+We can now instantiate an `action` object:
+
+```
+jshell> Action action = new Action()
+```
+
+And, given that `mavsdk_server` is running and connected to a (possibly simulated) drone, we can directly takeoff:
+
+```
+jshell> action.arm().andThen(action.takeoff()).subscribe()
+```

examples/java-client/build.gradle

@@ -29,6 +29,16 @@ task runMission(dependsOn: 'classes', type: JavaExec) {
     classpath = sourceSets.main.runtimeClasspath
 }
 
+task exportDeps(type: Copy) {
+    from sourceSets.main.runtimeClasspath into 'build/jshell_classpath_export/'
+}
+
+task jshell(dependsOn: 'exportDeps', type: Exec) {
+    print("\n\n=======\nWARNING: this is not the best way to run `jshell`, as it may not be cross-platform and it won't have auto-completion enabled.\nYou may want to run the following instead:\n\n    \$ ./gradlew exportDeps\n    \$ jshell --class-path \$(ls -d build/jshell_classpath_export/* | tr '\\n' ':')\n=======\n\n")
+    standardInput = System.in
+    commandLine 'bash', '-c', "jshell --class-path \$(ls -d build/jshell_classpath_export/* | tr '\\n' ':')"
+}
+
 task checkstyle(type: Checkstyle) {
     configFile = rootProject.file("config/checkstyle/checkstyle.xml")
     source 'src'

examples/java-client/settings.gradle

@@ -1,3 +1,7 @@
-rootProject.name = 'TakeoffAndLand'
+rootProject.name = 'MAVSDK-Java-example'
 
-includeBuild '../../sdk'
+// Uncomment the following line to use the SDK built from sources.
+// This will require `protoc-gen-dcsdk` to be in your PATH. See
+// the README in ../../sdk for more instructions about building
+// from sources.
+//includeBuild '../../sdk'

examples/java-client/src/main/java/io/mavsdk/example/TakeoffAndLand.java

@@ -16,9 +16,12 @@ public static void main(String[] args) {
     CountDownLatch latch = new CountDownLatch(1);
 
     action.arm()
+          .doOnComplete(() -> logger.debug("Arming..."))
           .andThen(action.takeoff())
+          .doOnComplete(() -> logger.debug("Taking off..."))
           .delay(5, TimeUnit.SECONDS)
           .andThen(action.land())
+          .doOnComplete(() -> logger.debug("Landing..."))
           .doOnComplete(() -> latch.countDown())
           .subscribe();
 

sdk/README.md

@@ -1,11 +1,50 @@
+# MAVSDK-Java - SDK
+
+This project is the actual Java SDK that gets deployed on [Maven Central](https://search.maven.org/search?q=a:mavsdk). It works by connecting to a running instance of `mavsdk_server`, that can be downloaded from the [MAVSDK release artifacts](https://github.com/mavlink/MAVSDK/releases). By default, it connects on a `mavsdk_server` instance running locally (i.e. on 'localhost'), but it can connect on any machine over the network.
+
+## Getting started
+
+Because it is deployed on Maven Central, adding MAVSDK-Java to your project is a matter of adding the dependency to your gradle file:
+
+```groovy
+dependencies {
+    implementation 'io.mavsdk:mavsdk:0.1.0'
+}
+```
+
+In your project, it can then be used to e.g. takeoff with the following (assuming an instance of `mavsdk_server` is running):
+
+```java
+import io.mavsdk.action.Action
+
+Action action = new Action();
+action.arm().andThen(action.takeoff()).subscribe();
+```
+
+Note that the MAVSDK-Java API is using [RxJava](https://github.com/ReactiveX/RxJava), for which extensive documentation can be found online. Don't forget to have a look at our [examples](../examples).
+
 ## Contributing
 
-The SDK implements the MAVSDK protobuf interfaces by using RxJava and TDD-style. This means that every single public method of a component must be unit-tested.
+MAVSDK-Java is mainly autogenerated from the MAVSDK [proto files](./proto), using our [protoc-gen-dcsdk plugin](./proto/pb_plugins) and [templates](./templates). Before starting contributing, learn to build from sources (below).
+
+## Building from sources
+
+### Prerequisites
+
+MAVSDK-Java is built using gradle, but `protoc-gen-dcsdk` must be in your PATH in order to auto-generate the code. It requires Python 3.6+ and can be built from `sdk/proto/pb_plugins` by running:
+
+```sh
+pip install -r requirements.txt
+pip install -e .
+```
+
+Make sure to add `protoc-gen-dcsdk` to your PATH!
 
-## Project organization
+### Building the SDK
 
-This is the root of the main "sdk" project, composed of multiple modules. Each module corresponds to a component defined by a protobuf interface (see [MAVSDK-Proto](https://github.com/mavlink/MAVSDK-Proto)).
+Once the prerequisites are met, the SDK can be built with:
 
-Each module is only building a specific part of the overall protobuf interface by using a symbolic link to the corresponding folder in MAVSDK-Proto (see for instance [the core module](https://github.com/mavlink/MAVSDK-Proto)).
+```sh
+./gradlew build
+```
 
-Most of the gradle setup is shared between the components and can be found in [build.gradle](./build.gradle).