🥮 mooncakes.io

madk

Transport-independent Android Open Accessory protocol support for MoonBit.

moonbit
android
usb
aoa
accessory
Download zip
Version
0.1.0
License
MIT
Repository
Last updated
yesterday
Downloads
21

#madk

madk is a MoonBit toolkit for hosts that communicate with Android devices through the Android Open Accessory (AOA) protocol.

The project keeps the protocol state machine independent from USB and platform details. Native USB access is provided by an optional libusb adapter; a simulator is available for deterministic tests.

#Status

madk is pre-1.0 software. Public MoonBit APIs, the WIT contract, and transport adapter behavior may change between releases.

#What it provides

  • AOA v1 accessory negotiation and bulk transport;
  • AOAv2 HID registration, descriptor transfer, and input events;
  • AOAv2 audio-mode negotiation with explicit capability errors;
  • transport interfaces for control and bulk transfers;
  • a deterministic simulator with failure injection;
  • a native libusb transport with runtime diagnostics;
  • a native AOA probe for end-to-end negotiation and fixture frame checks;
  • an Android fixture application for physical AOA acceptance tests;
  • a WIT host-capability contract for a future WASI integration.

#Package layout

PathPurpose
protocol.mbt, session.mbtportable AOA protocol state machine
transport/transport interfaces and shared transfer types
sim/deterministic simulator and tests
libusb/native libusb adapter
examples/native/aoa_probe/native libusb probe for physical AOA checks
wit/WASI host capability contract
examples/android/Android-side test fixture
docs/protocol and integration-boundary notes

#WASI boundary

WASI is an integration boundary, not a USB driver. A WASI component cannot access Android USB APIs or libusb directly. The host must provide a capability for device selection, control transfers, bulk transfers, timeouts, disconnects, and cleanup.

The current WIT file defines that host contract but does not embed a WASI runtime or provide a complete WASI adapter. See docs/wasi.md.

#Requirements

  • MoonBit compiler release 0.10.9+6e6c44045, selected by .moon-version;
  • a native C toolchain for native builds;
  • libusb 1.0 runtime and host USB permissions for physical native USB tests;
  • JDK 17, Android SDK, and Gradle 9.6.1 for the Android fixture;
  • adb from Android SDK platform-tools for wireless fixture deployment.

The pinned release bundles MoonBit compiler moonc 0.10.9+6e6c44045. The repository pins the exact release identifier because MoonBit is still evolving and compiler/API changes must be deliberate. Do not replace the version with the latest channel in local or CI setup.

#Build and test

The portable core and simulator do not require an Android device:

moon fmt --check
moon check --target native --deny-warn
moon test --target native --deny-warn
moon check --target all --deny-warn

The native probe package has an explicit CLI smoke test:

moon check examples/native/aoa_probe --target native --deny-warn
moon run examples/native/aoa_probe --target native -- --help

Build the Android fixture with:

cd examples/android
gradle :app:assembleDebug --no-daemon

The Android application does not perform the AOA handshake. A host must negotiate AOA, start accessory mode, handle USB re-enumeration, and then use the fixture's length-prefixed test frames. Physical Windows tests may require WinUSB on the Android Accessory interface and may require stopping a conflicting ADB service before opening the composite device with libusb.

#Native AOA probe

examples/native/aoa_probe/ uses LibusbTransport and AoaSession to perform the host-side AOA flow:

  1. select the normal Android device with --vid and --pid;
  2. query the AOA protocol and send the madk-fixture identity;
  3. start accessory mode and wait for USB re-enumeration;
  4. verify the status response and a length-prefixed echo response.

Use decimal IDs or 0x-prefixed hexadecimal IDs:

moon run examples/native/aoa_probe --target native -- --vid 0x18d1 --pid <normal-pid>

To connect to a device that is already in accessory mode, use --accessory instead of --vid and --pid:

moon run examples/native/aoa_probe --target native -- --accessory

The probe requires a loadable libusb 1.0 runtime. On Windows, bind WinUSB only to the Android Accessory interface and keep the ADB interface on its existing driver. A running ADB service may need to be stopped before the probe opens the accessory interface.

#Wireless Android fixture deployment

The fixture can be installed and started over wireless ADB:

./examples/android/deploy-wireless.ps1 -Device "<device-ip>:<debug-port>" -Build -ClearLog -DumpLog

The script searches adb in PATH, ANDROID_HOME, ANDROID_SDK_ROOT, and the default Windows SDK location. -Apk selects an existing APK, -Build builds the debug APK first, -ClearLog clears the device log, and -DumpLog prints the madk-fixture logcat stream. -AdbPath can override adb discovery.

Wireless deployment verifies APK installation, Activity startup, and Android logs only. It does not exercise the USB AOA negotiation or the native bulk transport; use a physical USB data connection and the native probe for that.

#Documentation

#License

madk is distributed under the MIT License.

AoaError

source
pub(all) suberror AoaError {
  InvalidState(String)
  InvalidIdentityField(Int)
  UnsupportedProtocol(Int)
  DeviceNotInAccessoryMode(Int)
  MissingBulkEndpoints
  ShortTransfer(Int, Int)
  UnsupportedFeature(AoaFeature)
  InvalidHidId(Int)
  HidAlreadyRegistered(Int)
  UnknownHid(Int)
  InvalidHidDescriptorLength(Int, Int)
  HidDescriptorNotReady(Int)
  Transport(
TransportError)
} derive(Eq, 
Debug)

AoaFeature

source
pub(all) enum AoaFeature {
  Bulk
  Hid
  Audio
} derive(Eq, 
Debug)

AoaIdentity

source
pub struct AoaIdentity {
  // private fields
} derive(Eq, 
Debug)

AoaIdentity::description

source
fn AoaIdentity::description(self : AoaIdentity) -> String

AoaIdentity::manufacturer

source
fn AoaIdentity::manufacturer(self : AoaIdentity) -> String

AoaIdentity::minimal

source
fn AoaIdentity::minimal(manufacturer~ : String, model~ : String, version~ : String) -> AoaIdentity raise AoaError

AoaIdentity::model

source
fn AoaIdentity::model(self : AoaIdentity) -> String

AoaIdentity::new

source
fn AoaIdentity::new(manufacturer~ : String, model~ : String, description~ : String, version~ : String, uri~ : String, serial~ : String) -> AoaIdentity raise AoaError

AoaIdentity::serial

source
fn AoaIdentity::serial(self : AoaIdentity) -> String

AoaIdentity::uri

source
fn AoaIdentity::uri(self : AoaIdentity) -> String

AoaIdentity::version

source
fn AoaIdentity::version(self : AoaIdentity) -> String

AoaProtocolVersion

source
pub(all) enum AoaProtocolVersion {
  V1
  V2
} derive(Eq, 
Debug)

AoaProtocolVersion::wire_value

source
fn AoaProtocolVersion::wire_value(self : AoaProtocolVersion) -> Int

AoaSession

source
pub struct AoaSession {
  // private fields
}

AoaSession::audio_capability

source
fn AoaSession::audio_capability(self : AoaSession) -> AudioCapability

AoaSession::audio_is_active

source
fn AoaSession::audio_is_active(self : AoaSession) -> Bool

AoaSession::audio_mode

source
fn AoaSession::audio_mode(self : AoaSession) -> AudioMode

AoaSession::close

source
fn AoaSession::close(self : AoaSession) -> Unit raise AoaError

AoaSession::configure

source
fn AoaSession::configure(self : AoaSession, identity : AoaIdentity, audio_mode? : AudioMode) -> Unit raise AoaError

AoaSession::device_info

source

AoaSession::new

source

AoaSession::probe

source

AoaSession::protocol

source
fn AoaSession::protocol(self : AoaSession) -> AoaProtocolVersion?

AoaSession::read_bulk

source
fn AoaSession::read_bulk(self : AoaSession, max_length : Int, timeout_ms : Int) -> Bytes raise AoaError

AoaSession::read_bulk_exact

source
fn AoaSession::read_bulk_exact(self : AoaSession, length : Int, timeout_ms : Int) -> Bytes raise AoaError

AoaSession::refresh_bulk_endpoints

source
fn AoaSession::refresh_bulk_endpoints(self : AoaSession) -> Unit raise AoaError

AoaSession::register_hid

source
fn AoaSession::register_hid(self : AoaSession, identifier~ : Int, descriptor_length~ : Int) -> HidDevice raise AoaError

AoaSession::send_hid_event

source
fn AoaSession::send_hid_event(self : AoaSession, device : HidDevice, report : Bytes) -> Unit raise AoaError

AoaSession::send_hid_report_descriptor

source
fn AoaSession::send_hid_report_descriptor(self : AoaSession, device : HidDevice, descriptor : Bytes, packet_size? : Int) -> Unit raise AoaError

AoaSession::set_audio_mode

source
fn AoaSession::set_audio_mode(self : AoaSession, mode : AudioMode) -> Unit raise AoaError

AoaSession::start

source
fn AoaSession::start(self : AoaSession) -> Unit raise AoaError

AoaSession::state

source
fn AoaSession::state(self : AoaSession) -> AoaState

AoaSession::supports

source
fn AoaSession::supports(self : AoaSession, feature : AoaFeature) -> Bool

AoaSession::unregister_hid

source
fn AoaSession::unregister_hid(self : AoaSession, device : HidDevice) -> Unit raise AoaError

AoaSession::write_bulk

source
fn AoaSession::write_bulk(self : AoaSession, payload : Bytes, timeout_ms : Int) -> Unit raise AoaError

AoaState

source
pub(all) enum AoaState {
  Detected
  Probed(AoaProtocolVersion)
  Configured
  Started
  BulkReady
  Closed
} derive(Eq, 
Debug)

AudioCapability

source
pub(all) enum AudioCapability {
  Unsupported
  Pcm44100Stereo
} derive(Eq, 
Debug)

AudioMode

source
pub(all) enum AudioMode {
  Disabled
  Pcm44100Stereo
} derive(Eq, 
Debug)

HidDevice

source
pub struct HidDevice {
  // private fields
} derive(Eq, 
Debug)

HidDevice::identifier

source
fn HidDevice::identifier(self : HidDevice) -> Int

accessory_adb_product_id

source
let accessory_adb_product_id : Int

accessory_audio_adb_product_id

source
let accessory_audio_adb_product_id : Int

accessory_audio_product_id

source
let accessory_audio_product_id : Int

accessory_get_protocol

source
let accessory_get_protocol : Int

accessory_product_id

source
let accessory_product_id : Int

accessory_register_hid

source
let accessory_register_hid : Int

accessory_send_hid_event

source
let accessory_send_hid_event : Int

accessory_send_string

source
let accessory_send_string : Int

accessory_set_audio_mode

source
let accessory_set_audio_mode : Int

accessory_set_hid_report_desc

source
let accessory_set_hid_report_desc : Int

accessory_start

source
let accessory_start : Int

accessory_unregister_hid

source
let accessory_unregister_hid : Int

aoa_vendor_id

source
let aoa_vendor_id : Int

audio_adb_product_id

source
let audio_adb_product_id : Int

audio_product_id

source
let audio_product_id : Int

default_control_timeout_ms

source
let default_control_timeout_ms : Int

usb_vendor_device_in

source
let usb_vendor_device_in : Int

usb_vendor_device_out

source
let usb_vendor_device_out : Int

Source Files

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io