An Android library (SDK) for connecting to Diode network endpoints and enabling bidirectional messaging. This SDK provides the core functionality for integrating Diode network connectivity into your Android applications.

• Connect to any Diode network peer by address
• Receive and send data packets to connected peers
• Embedded Elixir runtime for Diode network operations

• Android Library: Kotlin-based SDK providing Diode connectivity APIs
• Elixir Backend: Uses diode_client_ex to handle Diode network connections
• Bridge: TCP socket-based communication between Android and Elixir
• Native Components: Erlang VM launcher and static libraries

1. Android Studio with:

   • Android SDK
   • NDK (Side by side)
   • CMake

2. ASDF version manager:

   asdf plugin add erlang
   asdf plugin add elixir

3. diode_client_ex: The project requires the diode_client_ex library as a local dependency:

   • Clone or ensure diode_client_ex is located at ../diode_client_ex (sibling directory to this project)
   • The mix.exs file is configured to use this local path dependency
   • If you need to use a different location, update the path in elixir-app/mix.exs

4. Erlang Static Libraries: The native build requires Erlang static libraries (liberlang.a) for each target ABI:

   • app/src/main/libs/armeabi-v7a/liberlang.a
   • app/src/main/libs/arm64-v8a/liberlang.a
   • app/src/main/libs/x86_64/liberlang.a

   These libraries must be built from Erlang/OTP source for Android. See Erlang Native Build Requirements below.

Before building, ensure the diode_client_ex dependency is available. You have several options:

If you have a pre-built diode_client_ex binary (e.g., from Hex, a release archive, or a pre-compiled dependency):

1. If published to Hex.pm: Update elixir-app/mix.exs to use the Hex package:

   defp deps do
     [
       {:diode_client, "~> 1.1"},  # Use version from Hex
       {:jason, "~> 1.4"}
     ]
   end

2. If you have a pre-built .ez archive: Place the archive file (e.g., diode_client-1.1.0.ez) in elixir-app/deps/ and update mix.exs:

   defp deps do
     [
       {:diode_client, path: "deps/diode_client"},  # Extract archive to deps/diode_client
       {:jason, "~> 1.4"}
     ]
   end

   Then extract the archive:

   cd elixir-app/deps
   unzip diode_client-1.1.0.ez -d diode_client

3. If you have pre-compiled beam files: Place the compiled ebin/ directory in elixir-app/deps/diode_client/ and update mix.exs:

   defp deps do
     [
       {:diode_client, path: "deps/diode_client"},
       {:jason, "~> 1.4"}
     ]
   end

If you need to build from source or don't have a pre-built binary:

1. Check the directory structure: The project expects diode_client_ex to be located at:

   diode_android_sdk/
   └── diode_client_ex/  (sibling directory)
   

2. Clone or link diode_client_ex (if not already present):

   cd ..
   git clone <diode_client_ex_repository_url> diode_client_ex
   # Or if you already have it elsewhere:
   # ln -s /path/to/diode_client_ex ../diode_client_ex

3. Verify the dependency: The elixir-app/mix.exs file is configured to use:

   {:diode_client, path: "../diode_client_ex"}

   If your diode_client_ex is in a different location, update this path accordingly.

Note: When using a pre-built binary, you may skip the compilation step during mix deps.get, which can significantly speed up the build process.

cd elixir-app
asdf install  # Install Erlang and Elixir versions from .tool-versions
mix deps.get  # This will fetch diode_client_ex (from path, Hex, or pre-built binary)
./build_release.sh

This will create app/src/main/assets/app.zip.xz containing the Elixir release.

Note:

• If using a pre-built binary, mix deps.get will use it directly without compilation
• If using source code, the diode_client_ex dependency will be compiled and included in the release automatically by Mix
• The build process will work the same regardless of which dependency method you chose

Before building the Android library, you must have the Erlang static libraries in place:

1. Create the required directory structure:

   mkdir -p app/src/main/libs/armeabi-v7a
   mkdir -p app/src/main/libs/arm64-v8a
   mkdir -p app/src/main/libs/x86_64

2. Build or obtain liberlang.a for each ABI and place them in the corresponding directories.

   Note: Building Erlang for Android requires cross-compilation. You may need to:

   • Use a toolchain like erlang_android or similar
   • Cross-compile Erlang/OTP from source for each target architecture
   • Extract the static library from the compiled Erlang runtime

Build the library using Gradle:

./gradlew :app:assembleRelease

This will produce an AAR file at:

app/build/outputs/aar/app-release.aar

To publish the library to your local Maven repository for testing:

./gradlew :app:publishToMavenLocal

This will publish the library with coordinates:

• Group ID: io.diode
• Artifact ID: sdk
• Version: 1.0.0

You can then reference it in other projects as:

implementation 'io.diode:sdk:1.0.0'

To create a distributable AAR:

1. Build the release AAR:

   ./gradlew :app:assembleRelease

2. The AAR file will be located at app/build/outputs/aar/app-release.aar

3. For the example app: Copy the AAR to the example app's libs directory:

   cp app/build/outputs/aar/app-release.aar ../diode_android_example/app/libs/diode-sdk-release.aar

4. Optionally, you can also generate sources and documentation:

   ./gradlew :app:assembleRelease :app:generateSourcesJar

See the Example App for detailed instructions on integrating the SDK into your Android application.

1. Add the SDK as a Gradle dependency in your app module's build.gradle:

   dependencies {
       implementation 'io.diode:sdk:1.0.0'
   }

   Or if using a local AAR file:

   dependencies {
       implementation files('libs/diode-sdk-release.aar')
   }

2. Add the SDK dependency to your dependencies block to integrate the library into your Android app.

3. Download the AAR, place it in your project's libs directory, and configure your build script to treat it as a library dependency.

diode_android_sdk/
├── app/                    # Android library module
│   ├── src/main/
│   │   ├── java/io/diode/sdk/
│   │   │   └── Bridge.kt      # Android-Elixir bridge (main SDK API)
│   │   ├── cpp/               # Native Erlang launcher
│   │   ├── libs/              # Erlang static libraries (see libs/README.md)
│   │   └── assets/            # Elixir release (app.zip.xz)
│   └── build.gradle           # Library build configuration
├── elixir-app/            # Elixir application
│   ├── lib/diode_sdk/
│   │   ├── application.ex
│   │   ├── supervisor.ex
│   │   └── bridge.ex          # Elixir bridge handler
│   ├── mix.exs             # Uses diode_client_ex from ../diode_client_ex
│   └── build_release.sh
└── README.md

../diode_client_ex/        # Local dependency (sibling directory)
└── (diode_client_ex source code)

The native code (native-lib.cpp) links against Erlang static libraries. These must be built for Android's target architectures. The required libraries are:

• armeabi-v7a: 32-bit ARM (for older devices)
• arm64-v8a: 64-bit ARM (for most modern devices)
• x86_64: 64-bit x86 (for emulators)

Building Erlang static libraries for Android is a complex process that typically involves:

1. Setting up Android NDK toolchains for each target architecture
2. Configuring Erlang/OTP build system for cross-compilation
3. Building Erlang with Android-specific flags
4. Extracting the static library from the build output

You may need to:

• Use specialized build scripts or tools designed for Erlang on Android
• Modify Erlang's build configuration for Android targets
• Handle Android-specific system calls and library dependencies

Important: The Erlang version used to build the static libraries should match the Erlang version specified in elixir-app/.tool-versions (currently Erlang 28.2.2).

• Build fails with "diode_client dependency not found":
  • If using source code: Ensure diode_client_ex is located at ../diode_client_ex relative to this project, or update the path in elixir-app/mix.exs
  • If using Hex package: Ensure you have internet access and the package version exists on Hex.pm
  • If using pre-built binary: Verify the binary is in the correct location (e.g., elixir-app/deps/diode_client/ for extracted archives)
  • Verify the dependency configuration in elixir-app/mix.exs matches your chosen method
  • Run mix deps.get in the elixir-app directory to fetch dependencies
• Build is slow when using source code: Consider using a pre-built binary if available to skip compilation
• Build fails with "liberlang.a not found": Ensure the Erlang static libraries are in the correct app/src/main/libs/{abi}/ directories
• Build fails: Ensure ASDF is installed and Erlang/Elixir versions match .tool-versions
• Native build errors: Verify NDK is installed and ndkVersion in build.gradle matches your installed NDK version
• AAR build fails: Ensure all prerequisites are met and the Elixir release has been built successfully