CoffeeBeam: a BEAM VM for Android

Goal

CoffeeBeam is a lightweight Erlang virtual machine that provides easy integration of BEAM files with Android applications. The current alternative solutions provide almost fully functional Erlang runtime systems in the form of Erlang shell on Android devices. However, CoffeeBeam follows a different approach, targeting easy integration of pre-compiled BEAM files into standalone Android applications. The characteristics of Android devices are in focus: they provide large amount of memory while CPU usage needs to be optimized to provide longer device lifetime. It is preferred to make the communication between Erlang and the Android application transparent to provide better user experience.

Use Case

Let's assume that you chose a language over the BEAM to implement an application logic efficiently. CoffeeBeam provides a framework to build on this logic and enable communication between the BEAM and the Android application with only minor changes to your original code. The demonstrated example is a TicTacToe game where the game logic is implemented in Erlang that is extended with a graphical user interface implemented as an Android activity in Java.

Application Architecture

Android Activity

The TicTacToe game is implemented as an Android activity which is a common way of creating interactive applications. The activity contains the view for displaying textual information (game name and user instructions depending on the state of the game) and widgets (game board and new game button) for initiating user actions towards the game logic.

CoffeeBeam VM

The CoffeBeam VM provides the runtime system for the game logic. It is written in Java and included as a .jar library inside the Android application source code. Starting and stopping the VM is connected to the onCreate() and onDestroy() callbacks of the activity.

Game logic

The flow of the game and the computer player's intelligence is implemented as an Erlang module (approximately 250 lines of code) and the compiled .beam file is packaged into the Android application as resource.

Communication

The BeamClient class provides interface for starting and stopping the VM, and manages communication between the VM and the Android application through function calls and callback functions. The default behavior can be redefined by extending the BeamClient class. The forms of communication are described in detail below.

Function call in the VM

User actions in the Android application are translated into function calls in the VM using the apply(String module, String function, ErlList args) method of the BeamClient class. The function call implies creating a new process in the Erlang VM and applying module:function with the list of args. The TicTacToe game logic provides the following functions:

• Start the game process: start(). The game process is spawned that initializes the board for a new game.
• Start a new game: new_game(GamePid). The game board is cleared and a new game starts in the game process identified by GamePid.
• The player selects a field: put(GamePid, X, Y). The player marks the (X,Y) field of the game board with an X sign.

Handle function result in Android

When the Erlang function is executed in the VM, the result of the function initiates a callback in the BeamClient as handleResult(ErlTerm result). In the TicTacToe example, the process identifier of the game process is returned as the result of the tictactoe:start() function. The returned value can be used to send Erlang messages to the game process during the game.

Handle function callback in Android

Each call in the form of beamclient:function(arg) in the Erlang modules results in a BeamClient callback handleCall(String function, ErlTerm arg). Each game event invokes a beamclient:update({Event, Board}) function call that is translated into handleCall callback in the Android application.

Summary and contribution

CoffeeBeam executes BEAM files in a lightweight VM that can be packaged into the Android application. The above TicTacToe example showed how to include the Erlang game logic in the Android application that provides the graphical user interface. The game flow runs in a separate process in the CoffeBeam VM, and the communication with Android is done through BeamClient function calls and callbacks.

The CoffeeBeam VM is open source and available for further development to extend the VM functionality or implement customizations for other languages running on the BEAM. The source code with documented interface is available at: https://github.com/vikger/coffeebeam.