Onyx SDK recovered source

This repository is a source-only reconstruction of seven independently built Onyx/BOOX Android libraries, including two recovered support artifacts and an additive Kotlin companion. It contains no tracked original SDK JAR, AAR, or native library.

The public Kotlin API reference is available on GitHub Pages.

The transitive onyxsdk-pen API includes both generations of the Java API: the 57 classes from the 1.5.4 SDK and the 72 classes supplied with the newer native pen API. Four self-contained modern bindings and their single JNI library live in onyxsdk-pen-core, which onyxsdk-pen exposes with an api dependency. The combined 129-class surface is checked against all 118 public reference classes. The base module's surface is additionally verified by a classified descriptor/flags/signature/metadata audit against its reference JAR and pinned by an in-tree regression test (see RECOVERY_NOTES.md). The references are analysis inputs only and are never Gradle inputs, tracked files, or AAR contents.

Module architecture and provenance

The module names preserve the original Onyx Maven artifacts; they do not form a conventional bottom-up layering. In particular, onyxsdk-base is the broad application-facing SDK, not the lowest-level module. It builds on the smaller device and support artifacts and exposes them transitively through Gradle's api configuration.

The production dependency direction is:

onyxsdk-ktx -----> onyxsdk-pen -----> onyxsdk-pen-core
      |                  |
      +------------------+----------> onyxsdk-base

onyxsdk-base ----> onyxsdk-device
             +---> onyxsdk-baselite
             +---> onyxsdk-commons-io

Each arrow means "depends on". onyxsdk-ktx depends directly on both pen and base; pen exposes pen-core transitively and also depends on base.

The modules have distinct responsibilities:

Baselite 1.1.1 and Onyx Commons IO 2.5 were separate compile dependencies in the original onyxsdk-base:1.8.5 POM, published under com.onyx.android.sdk through the BOOX Maven repository. They were not embedded in the base classes.jar. This repository replaces their original AARs with the source-built modules under onyxsdk-base/support; their nested location is a repository convenience rather than an indication that they were private implementation code. Commons IO retains its Apache license headers and relocated package names, while Baselite retains the Onyx-specific class and Kotlin/JVM surface expected by base and pen.

Treat onyxsdk-base, onyxsdk-device, onyxsdk-pen, and both support modules as compatibility artifacts. Avoid renaming their legacy packages, merging the support classes into base, or splitting base classes into new AARs unless the artifact and JVM contract change is intentional. Prefer implementation for new internal dependencies, keep api only where the public or historical dependency contract requires it, and put additive Kotlin APIs in onyxsdk-ktx. Any boundary or dependency change must pass ./gradlew check, including the per-AAR JVM contract verification.

The exact package-owner map is registry-controlled. Base owns com.onyx.android.sdk.utils; Device retains only eight historical exceptions in that package: ClassUtils, Debug, DeviceBroadcastHelper, LightUtils, MagnifierUtils, ReflectUtil, Singleton, and SystemPropertiesUtil. verifyModuleBoundaries rejects a ninth Device utility, a moved exception, another split package, duplicate classes between AARs, or support-owned Baselite/Commons IO classes appearing in Base.

Distribution and licensing

The seven release AARs are independent Maven publications under io.github.hbmartin.onyx. Their artifact IDs and recovered-source versions are declared once in gradle/onyx-modules.json, which also drives Gradle project inclusion, aggregate builds, validation inputs, package ownership, and release staging. AAR paths and production task lists must not be duplicated in build or validation configuration.

Recovered first-party code is distributed under the GNU Lesser General Public License v3.0 only; see LICENSE.txt and its incorporated LICENSES/GPL-3.0.txt terms. The separately published, relocated onyxsdk-commons-io module remains Apache-2.0 and retains its source headers; see LICENSES/Apache-2.0.txt. This exception preserves third-party provenance and does not change the license of the other six artifacts.

Every release publication contains the unchanged source-built AAR plus Maven POM and Gradle module metadata, sources, and Javadoc artifacts. Generate and audit credential-free publication output with:

./gradlew verifyPublicationMetadata stageGithubRelease

verifyCentralBundle additionally requires MAVEN_SIGNING_KEY and MAVEN_SIGNING_PASSWORD and produces the signed Central Portal bundle under build/distributions/central/. Tag CI supplies those signing values and the MAVEN_CENTRAL_USERNAME / MAVEN_CENTRAL_PASSWORD Portal token, uploads only new coordinates, skips byte-identical coordinates, and publishes automatically after Portal validation. Run the signed task with --no-configuration-cache, as the built-in Gradle signing plugin consumes the private key during configuration; tag CI already enforces that flag.

Pen native implementation

The pen artifacts build two native implementations entirely from Rust and package three JNI sonames:

• libonyx_pen_touch_reader.so implements the 11 RawInputReader JNI calls, Linux input discovery/polling, pen and eraser states, pressure processing, and region filtering;
• libneo_pen.so exports the seven NeoPenNative functions — five are declared native methods on the recovered class; nativeSetBitmapColor and nativeSetLogLevel are exported only to match the reference library's surface — and the seven legacy NeoPenWrapper calls, including all nine pen types, prediction, texture bitmaps, handle lifecycle, and the legacy static API. This compatibility soname is packaged by onyxsdk-pen;
• libneopen_jni.so is the modern alias of the same renderer binary and is packaged alone by onyxsdk-pen-core.

Both libraries are built for armeabi-v7a, arm64-v8a, x86, and x86_64. They do not depend on libc++_shared.so.

The BOOX device differential harness executes the supplied reference and the Rust library through the same Java API. Instrumentation tests assert exact recovered values for pen types 1–3; exactness for the texture types 4–5 is checked only by the optional on-device differential gate, whose snapshot comparison covers stamp positions plus bitmap dimensions and a pixel-content digest. Types 6–9 use an independent Wacom-style spline/brush implementation and are checked for the same buffering, prediction, record encoding, bitmap behavior, and bounded output geometry.

The existing fountain renderer remains the default. An additive, opt-in reference-compatible renderer consumes smoothing, velocity, pressure, tilt, direction, and brush configuration while preserving both Java API generations and their JNI/record contracts. The device module also exposes advanced stroke configuration, capability checks, and a firmware-configured Binder transport with stroke-scoped fallback and failure handling. See docs/STROKE_COMPATIBILITY.md.

Build and test

Prerequisites are JDK 17+, Rust stable, Android SDK platform 35, and Android NDK 28.2.13676358. Set ANDROID_HOME or ANDROID_SDK_ROOT when needed.

./gradlew clean :check assembleRecovered

That gate compiles all production Java/Kotlin, tests the recovery behaviors, runs Rust tests and Clippy, builds the native implementations, packages all 12 ABI/soname entries, assembles all seven production AARs, and verifies every JNI export and packaged native dependency. It deliberately runs each module's unit tests in a single variant (the Java bytecode is variant-identical) and leaves instrumentation and differential checks to the hardware gates below.

With a connected BOOX device and the untracked analysis reference, run the additional differential gate:

scripts/device-pen-differential.sh /path/to/reference/neo-pen-library DEVICE_SERIAL

To repeat the JVM API comparison against the two untracked reference JARs:

scripts/verify-pen-api.py \
  --old-reference /path/to/onyxsdk-pen-1.5.4/classes.jar \
  --native-reference /path/to/reference-artifacts/onyxsdk-pen-native-classes.jar \
  --candidate onyxsdk-pen/build/intermediates/aar_main_jar/release/syncReleaseLibJars/classes.jar \
  --candidate-dependency onyxsdk-pen-core/build/intermediates/aar_main_jar/release/syncReleaseLibJars/classes.jar

See RECOVERY_NOTES.md, docs/VALIDATION.md, and docs/NATIVE_RECOVERY.md. The constraints and gates for the planned Java-to-Kotlin conversion are documented in docs/KOTLIN_MIGRATION.md.

Demo and test app

device-validation/app is an installable comparison and demonstration app for a BOOX device. It has reference and recovered flavors with the same application ID, so the runner installs them sequentially and exercises the same firmware paths. Keep the original analysis inputs in a separate directory and pass that directory explicitly.

The reference directory must contain these inputs:

reference-artifacts/
├── onyxsdk-base-1.8.5/classes.jar
├── onyxsdk-device-1.3.5/classes.jar
├── onyxsdk-pen-1.5.4/
│   ├── classes.jar
│   └── jni/                 # original ABI-specific native libraries
└── onyxsdk-pen-native-classes.jar

Set ANDROID_HOME or ANDROID_SDK_ROOT, authorize the device with adb, and run a guided drawing demo from the repository root:

device-validation/run-comparison.sh \
  --artifacts-root /path/to/reference-artifacts \
  --serial DEVICE_SERIAL \
  --suite pen-live \
  --duration-ms 30000

The screen shows a drawing canvas plus limit, exclude, single-region, pause, clear, and finish controls. The runner builds both flavors, installs each one, captures events, and writes its report under device-validation/results/. Use --suite sdk-automated, sdk-ink, automated, base, device, mmkv-compat, pen-replay, neo-pen, or guided for the other test modes. The automated and neo-pen suites also require --neo-pen-reference /path/to/reference/neo-pen-library.

To install only the recovered flavor for manual exploration:

./gradlew assembleRecovered
./gradlew -p device-validation \
  -POnyxArtifactsRoot=/path/to/reference-artifacts \
  :app:assembleRecoveredDebug
adb install -r device-validation/app/build/outputs/apk/recovered/debug/app-recovered-debug.apk
adb shell am start -n com.onyx.recovery.validation/.ValidationActivity \
  --es suite pen-live --el durationMs 30000

Host-only validation for the app's comparison code does not need a device:

python3 -m unittest discover device-validation/tests

Dependency catalog (non-Cargo)

Vendored

• Onyx Baselite 1.1.1 recovered source in onyxsdk-base/support/onyxsdk-baselite.
• Apache Commons IO 2.5 recovered and package-relocated source in onyxsdk-base/support/onyxsdk-commons-io.
• Gradle Wrapper 9.6.1 bootstrap files in gradle/wrapper.

Gradle

The version catalog and module build scripts declare the following external Gradle dependencies; Gradle resolves their transitive dependencies:

• Build plugins: Android application/library 9.2.1, Kotlin Android 2.0.21, Dokka 2.2.0, Detekt 1.23.8, and Ben Manes Versions 0.54.0.
• AndroidX: annotation 1.0.0 and 1.9.1, appcompat 1.7.1, databinding-common 4.1.3, dynamicanimation 1.1.0-alpha03, fragment 1.8.8, Test JUnit extension 1.2.1, and Test Runner 1.6.2.
• Data and storage: Fastjson2 2.0.48.android8, MMKV 1.3.14, and Zip4j 2.11.5.
• Utilities: Commons Lang 3.18.0, EventBus 3.0.0, Kotlin standard library JDK 8 2.0.21, Kotlin coroutines 1.6.4, RxJava 2.1.13, and RxAndroid 2.1.0.
• Tests: JUnit 4.13.2, JUnit BOM 5.11.4 with JUnit Jupiter and the JUnit Platform Launcher, Robolectric 4.14.1, and JSON-java 20240303.

All Gradle/Maven coordinates and plugin versions live in gradle/libs.versions.toml, apart from the Foojay settings-bootstrap plugin, whose version must be available before catalogs are resolved. To inspect available stable dependency and Gradle updates, run:

./gradlew --no-parallel dependencyUpdates

Gradle 9 requires this task to run without parallel project execution.

EasyPermissions was previously exposed accidentally through onyxsdk-base's Gradle api configuration even though no production source used it. Its removal changes that transitive dependency surface but removes no Onyx SDK class or method. MMKV compatibility with files written by 1.0.19 is covered by the mmkv-compat device suite described in device-validation/README.md.