1 add support for gpio (#3)

* Add GPIO support

* Added examples

* Updated README.md

* Fixed docs generation

Author: orenskl

.github/workflows/main.yml

@@ -51,7 +51,10 @@ jobs:
 
     - name: Build Pico
       run: cmake --build ${{github.workspace}}/build.pico --config ${{env.BUILD_TYPE}}
-      
+
+    - name: Package Pico tar ball
+      run: cpack -B ${{github.workspace}}/build.pico --config ${{github.workspace}}/build.pico/CPackConfig.cmake -G TGZ
+
     - name: Release
       uses: softprops/action-gh-release@v1
       if: startsWith(github.ref, 'refs/tags/')

.gitignore

@@ -1,3 +1,4 @@
 /build
 /build.*
-/test/*.class
+/test/*.class
+/examples/*/build/*

.vscode/settings.json

@@ -3,4 +3,8 @@
     "files.associations": {
         "*.inc": "cpp"
     },
+    "java.project.sourcePaths": [
+        "cldc/src/javaapi/device",
+        "examples/src"
+    ],
 }

CMakeLists.txt

@@ -2,17 +2,44 @@
 
 # Pico JVM
 
-This is a Java virtual machine for the [Raspberry Pi Pico](https://www.raspberrypi.com/products/raspberry-pi-pico/), this project is based on the [CLDC](https://en.wikipedia.org/wiki/Connected_Limited_Device_Configuration) virtual machine and more specificly on the [phoneME](https://phonej2me.github.io) project from Sun/Oracle. The [phoneME](https://phonej2me.github.io) is a very old project that currently is not maintaned anymore. However I was able to find a github [repo](https://github.com/magicus/phoneME) that I used as a reference. This JVM is targeted to small embedded devices with limited resources so don't expected a full blown Java experience on [Raspberry Pi Pico](https://www.raspberrypi.com/products/raspberry-pi-pico/).
+This is a Java virtual machine for the [Raspberry Pi Pico](https://www.raspberrypi.com/products/raspberry-pi-pico/), this project is based on the [CLDC](https://en.wikipedia.org/wiki/Connected_Limited_Device_Configuration) virtual machine and more specifically on the [phoneME](https://phonej2me.github.io) project from Sun/Oracle. The [phoneME](https://phonej2me.github.io) is a very old project that currently is not maintained anymore. However I was able to find a github [repo](https://github.com/magicus/phoneME) that I used as a reference. This JVM is targeted to small embedded devices with limited resources so don't expected a full blown Java experience on [Raspberry Pi Pico](https://www.raspberrypi.com/products/raspberry-pi-pico/).
 
 The original [phoneME](https://phonej2me.github.io) project used a Makefile based build system, I converted the build system to CMake so I can use more modern tools and integration with modern CI/CD workflows. There are currently two main targets : Linux (used mainly for debugging) and Pico.
 
 Currently the JVM support [CLDC 1.1](https://docs.oracle.com/javame/config/cldc/ref-impl/cldc1.1/jsr139/index.html) specification which is a limited subset of the Java  J2SE specification and language.
 
-## Running a Java application
+## Installation and setup
 
-To run a Java application on the [Raspberry Pi Pico](https://www.raspberrypi.com/products/raspberry-pi-pico/) you will need to flash the Java virtual machine itself and than flash the Java application at the address `0x10100000`.
+Download the release package from the [Releases](https://github.com/orenskl/pico-jvm/releases) page of this repository, extract the package. The package contains the following content :
+
+```
+├── bin
+├── doc
+├── lib
+└── pjvm-X.Y.Z.uf2
+```
+
+The `bin` directory contains tools and scripts required to post process class and jar files to be able to run them on the [Raspberry Pi Pico](https://www.raspberrypi.com/products/raspberry-pi-pico/).
+
+The `doc` directory contains the javadoc for the device specific (e.g. GPIO) classes.
+
+The `lib` directory contains the run-time class libraries (`classes.jar`)
+
+The `pjvm-X.Y.Z.uf2` (where X.Y.Z is the version of the firmware) is the Java Virtual Machine UF2 file, this file needs to be flashed to the [Raspberry Pi Pico](https://www.raspberrypi.com/products/raspberry-pi-pico/) using [picotool](https://github.com/raspberrypi/picotool). The virtual machine already contains the run time classes so these are not required to be flashed separately.
 
-The Java VM can be dowloaded from the [Releases](https://github.com/orenskl/pico-jvm/releases) page of this project. You can download the gzipped UF2 file, unpack it and flash it with the standard [picotool](https://github.com/raspberrypi/picotool).
+The `examples` directory in this repository contains some examples you can run with an [Ant](https://ant.apache.org) `build.xml` file. To build the examples and the following Hello World application you will need to setup the environment variable `JAVA_PICO_HOME` to point to the extracted package location.
+
+For example if you extracted the package to `/opt/pjvm-X.Y.Z` you will need to setup the variable with the following command :
+
+```
+export JAVA_PICO_HOME=/opt/pjvm-X.Y.Z
+```
+
+You will also need [JDK 8](https://www.oracle.com/java/technologies/javase/javase8-archive-downloads.html) to build application, currently the latest versions of Java are not supported.
+
+## Building and running a Java application
+
+To run a Java application on the [Raspberry Pi Pico](https://www.raspberrypi.com/products/raspberry-pi-pico/) you will need to flash the Java virtual machine itself and than flash the Java application at the address `0x10100000`.
 
 Lets say we have a simple hello world application :
 
@@ -24,34 +51,52 @@ class Main {
 }
 ```
 
-The name of the class `Main` is currently fixed as the first class that is loaded by the VM. Compiler the class :
+**NOTE : The name of the class `Main` is currently fixed as the first class that is loaded by the VM.**
 
-```
-javac -source 1.4 -target 1.4 -d main.dir -bootclasspath ../pico-jvm/build/classes.jar Main.java
-```
+1. Compile the class :
 
-Make sure your `-bootclasspath` is correct and should point to the `classes.jar` that is built earilier
+    ```
+    javac -source 1.4 -target 1.4 -d main.dir -bootclasspath $JAVA_PICO_HOME/lib/classes.jar Main.java
+    ```
 
-Package the application as a JAR file :
+    Make sure to setup you environment correctly so that `JAVA_PICO_HOME` points to the right place (see [here](#installation-and-setup))
 
-```
-cd main.dir
-jar -cfM0 ../main.jar .
-```
+2. Preverify the classes
 
-Now we need to wrap the JAR with a header so we can run it on the Pi Pico :
+    Before running the compiled classes on the [Raspberry Pi Pico](https://www.raspberrypi.com/products/raspberry-pi-pico/) we will need to Preverify them. Preverifying is the process of post processing the class files so they can be run more efficiently on the target system. Preverifying is done with the `preverify` tool in the `bin` directory of the package.
 
-```
-tools/wrapjar.sh main.jar main.jar.bin
-```
+    ```
+    $JAVA_PICO_HOME/bin/preverify -d main.preverify -classpath $JAVA_PICO_HOME/lib/classes.jar main.dir
+    ```
 
-The `wrapjar` script is located in the `tools` directory of this project. Now we can flash the application to address `0x10100000` using `picotool` :
+3. Package the application as a JAR file :
 
-```
-picotool load build/main.jar.bin --offset 10100000
-```
+    ```
+    cd main.preverify
+    jar -cfM0 ../main.jar .
+    ```
+
+4. Wrap the JAR file 
+
+    Now we need to wrap the JAR with a header so we can run it on the Pi Pico :
+
+    ```
+    $JAVA_PICO_HOME/bin/wrapjar.sh main.jar main.jar.bin
+    ```
+
+    The `wrapjar.sh` script is located in the `bin` directory of the package.
+
+5. Flash the binary file and reboot
+
+    Now we can flash the application to address `0x10100000` using `picotool` :
+
+    ```
+    picotool load build/main.jar.bin --offset 10100000
+    ```
+
+    Reboot your Pi Pico and you should see `Hello, World!` on your terminal
 
-Reboot your Pi Pico and you should see `Hello, World!` on your terminal
+This repository includes an `example` directory with a complete [Ant](https://ant.apache.org) `build.xml` for each example that runs all the above steps in a single command.
 
 ## Building
 

README.md

@@ -0,0 +1,118 @@
+/*
+ * 
+ * SPDX-License-Identifier: GPL-2.0-or-later
+ * Copyright (C) 2024 Oren Sokoler (https://github.com/orenskl)
+ * 
+ */
+
+package pico.hardware;
+
+/**
+ * A <code>GPIOPin</code> represents a single GPIO pin, it can be configured
+ * to be either as an input or as an output. If configures as an input it can
+ * have a pull up or pull down resistor. Each GPIO pin is identified by its
+ * number, this number is passed directly to the hardware libray of the 
+ * device without any encoding or decoding.
+ */
+public class GPIOPin {
+
+    /**
+     * Output direction for the GPIO pin
+     */
+    public static final int OUT = 1;
+
+    /**
+     * Input direction for the GPIO pin
+     */
+    public static final int IN  = 0;
+
+    /**
+     * High (High voltage) for a GPIO pin
+     */
+    public static final int HIGH = 1;
+
+    /**
+     * Low (Low voltage 0V) for a GPIO pin
+     */
+    public static final int LOW  = 0;
+
+    /**
+     * A pull up resistor is connected to the pin
+     */
+    public static final int PULLUP = 1;
+
+    /**
+     * A pull down resistor is connected to the pin
+     */
+    public static final int PULLDOWN  = 0;
+
+    /**
+     * The GPIO pin number
+     */
+    private int pinNumber;
+
+    /**
+     * 
+     * Constructor for a GPIO pin
+     * 
+     * @param pinNumber The pin number
+     * @param pinType The pin direction ({@link GPIOPin#OUT} or {@link GPIOPin#IN})
+     * 
+     * @throws IllegalArgumentException
+     * 
+     */
+    public GPIOPin( int pinNumber, int pinType ) {
+        if ((pinType != OUT) && (pinType != IN)) {
+            throw new IllegalArgumentException();
+        } 
+        this.pinNumber = pinNumber;
+        gpio_init(pinNumber,pinType);
+    }
+
+    /**
+     * 
+     * Constructor for a GPIO pin with a pull up or pull down resistor
+     * 
+     * @param pinNumber The pin number
+     * @param pinType The pin direction ({@link GPIOPin#OUT} or {@link GPIOPin#IN})
+     * @param pinPull The resistor type ({@link GPIOPin#PULLUP} or {@link GPIOPin#PULLDOWN})
+     * 
+     * @throws IllegalArgumentException
+     * 
+     */
+    public GPIOPin( int pinNumber, int pinType, int pinPull) {
+        this(pinNumber,pinType);
+        if ((pinPull != PULLUP) && (pinPull != PULLDOWN)) {
+            throw new IllegalArgumentException();
+        } 
+        gpio_set_pull(pinNumber,pinPull);
+    }
+
+    /**
+     * 
+     * Set the state of the pin to either HIGH or LOW
+     * 
+     * @param pinState the state of the pin ({@link GPIOPin#HIGH} or {@link GPIOPin#LOW})
+     */
+    public void set ( int pinState ) {
+        gpio_set(this.pinNumber,pinState);
+    }
+
+    /**
+     * Get the state of the pin ({@link GPIOPin#HIGH} or {@link GPIOPin#LOW})
+     * 
+     * @return state of the pin
+     */
+    public int get () {
+        return gpio_get(this.pinNumber);
+    }
+
+    /*
+     * Natives for the device hardware
+     */
+    private static native void gpio_init     ( int pinNumber , int pinType );
+    private static native void gpio_set      ( int pinNumber , int pinState );
+    private static native int  gpio_get      ( int pinNumber );
+    private static native void gpio_set_pull ( int pinNumber , int pinPull );
+
+}

cldc/src/javaapi/device/pico/hardware/GPIOPin.java

@@ -23,6 +23,8 @@
 
 #include "OS.hpp"
 
+#include "pico/time.h"
+
 static bool             ticker_stopping = false;
 static bool             ticker_running = false;
 static int              sock_initialized = 0;
@@ -52,27 +54,31 @@ jlong offset() {
 }
 
 #if SUPPORTS_MONOTONIC_CLOCK
-jlong Os::monotonic_time_millis() {
+jlong Os::monotonic_time_millis() 
+{
   /*
    * Get the monotonic time in milliseconds from some unspecified starting
    * point. This clock must be monotonic and must have resolution and read
    * time not lower than that of Os::java_time_millis().
    */
-  return 0;
+  return time_us_64() / 1000;
 }
 #endif
 
-jlong Os::java_time_millis() {
+jlong Os::java_time_millis() 
+{
   /*
    * Get the current system time, unit: millisecond, count time from
    * Jan. 1st, 1970. Need reduce the OS dependent offset time value, if
    * the offset exist
    */
-  return 0;
+  return time_us_64() / 1000;
 }
 
-void Os::sleep(jlong ms) {
+void Os::sleep(jlong ms) 
+{
   /* let the current process sleep for ms seconds */
+  sleep_ms(ms);
 }