The Scripting Layer for Android, SL4A, is an open source application that allows programs written in a range of interpreted languages to run on Android. It also provides a high level API that allows these programs to interact with the Android device, making it easy to do stuff like accessing sensor data, sending an SMS, rendering user interfaces and so on.
It’s is really easy to install and it works on any stock Android device, so you don’t need to be root or anything like that.
You can find out more about the SL4A project from their website.
Why Android’s SL4A is Different
There are a couple of other options for running Python on Android, and some are very good, but none offer the flexibility and features of the Scripting Layer. The alternatives really focus on enabling you to create and package a native app using some otherwise unsupported language, and some do that really well. For example, with Kivy, you can create an app in Python that’ll run across many popular operating systems, desktop and smartphone, including Android. However because it’s multi-platform, you don’t have any way of directly accessing the Android API, so you can’t use many of the features that make smartphones so interesting.
SL4A was designed around the Android OS: It requires Android to be useful, but allows much closer integration with the operating system.
With SL4A, you can still package your apps, and you can publish them to app stores like Play if you like, but it’s just an option. One advantage to having packaging as an option, rather than as a purpose, is that most Python scripts, in practice, are not actually published through app stores anyway. They’re meant to be used as regular Python programs. You’ll normally just want to write a bit of code, save it, then run it, and keep iterating. Having to keep building the app is just tedious.
With the Scripting Layer, you can start hacking away like you would on any other system, just editing and executing files.
The Plunge: Getting Things Set Up
SL4A is really easy to install. The application is distributed as an APK, the standard format for Android apps, so it can be installed in the same way. However, before installing apps from ‘unknown sources’, you need to allow that on your device. If you haven’t already, open your device’s main Settings menu, open the Security menu, then “allow installation of non-Market apps” by checking the Unknown Sources option. Now you’re ready to install the Scripting Layer.
The Scripting Layer (SL4A)
If you go to the SL4A project’s home page, you can download a copy of the Scripting Layer APK to your device by just scanning the barcode on that page and confirming the download when prompted. If you don’t have a barcode scanner on your device, there’s always a bunch of gratis scanners available from any app store.
Once you’ve downloaded the APK, you should be able to install it from directly within your device’s notifications panel, where the download will appear. You device may differ slightly, but it will be obvious how you install the APK, as long as you’ve enabled installation from unknown sources.
Once you’ve installed the Scripting Layer, you’ll be able to open it, create and edit little shell scripts with the built-in editor and run them. It very easy to get started.
Whenever you first open SL4A, you’ll see the contents of your scripts directory, which lives at
/sdcard/sl4a/scripts. This is where you’ll normally put your own scripts for easy access. You can create directories in here to help keep things sane if you want to build more complex applications, or just to organise simple scripts if you have a lot of them.
The SL4A Interpreters
SL4A only includes the shell as standard, but installing other interpreters is easy to do from within the app. If you open SL4A, then hit your devices main menu button, and the SL4A menu will pop up. If you press View, you’ll see a menu with three options, Interpreters, Triggers and Logcat. Selecting Interpreters will move your view from the scripts directory to the interpreters list. Hitting the device’s main menu button in this view will open a new menu with an option to add interpreters. From here you can select which interpreter you want to install, which will open your browser and download the APK for that interpreter. Install this APK in the same way that you installed SL4A.
Each interpreter exists as a separate Android app and will appear as an app in the device’s menus. The Python Interpreter’s app is called Python for Android, or just PY4A. Each interpreter’s app has, at least, the ability to install or uninstall the interpreter. PY4A can also manage .egg files, which gives you an easy way to install Python C modules on the Scripting Layer, where you can otherwise only use pure Python. Any Python C modules must first be cross-compiled for ARM cores, which is an involved process, but some useful packages are available pre-compiled from the Python for Android project pages, along with instructions on how to compile others.
If you haven’t already, open the Python for Android app and hit the Install button. Your Scripting Layer now supports Python.
The Python Library on SL4A
If you’d like to add new modules to extend the device’s Python library, you have to do things a bit differently to what you’re probably used to. Without root, you can’t directly modify the system files, so the Scripting Layer has its own directory for packages that lives on your sdcard at
/sdcard/com.googlecode.pythonforandroid/extras/python. You can always import from this directory and similar directories exist for each language you have installed.
The Python extras directory comes preloaded with a ton of useful modules, and you can chuck any pure Python modules you like in here.
If you add a module to the extras directory, make sure it’s the importable Python module itself. When you grab a library from a repository, it’ll normally be structured so that the app’s root directory contains a bunch of stuff like READMEs, docs, tests and setup files, as well as the actual module you need, which may be a file or a directory. Remember, it must be pure Python and you will have to resolve any dependencies.
Note: If you don’t have a decent file browser on your device, grab one immediately. I normally use ES File Explorer which is free on Play. If you want to get seriously into hacking Androids, it’s a good idea to install the Android SDK on a dev box sooner rather than later too. It includes tools that make light work of some common tasks. It’s a fairly complex bit of kit, but guides for each OS are readily available online, and you’ll need it to package apps.
Android’s SL4A Hello World: Your First Script and the API
You have a bunch of example scripts installed automatically in the scripts directory whenever you add a new interpreter. These are a good place to start looking for code examples, and you can safely delete them once you’re done.
Using SL4A in Python is really simple. Most scripts start with the following two lines:
from android import Android droid = Android()
From here, the name
droid is an
Android object and acts as a hook to the Android device. You use it to access the entire Scripting Layer API. The API is divided into sections called facades, with each facade covering some area of the API, such as Webviews, Phone, WiFi, Events, Camera, Battery and so on.
For example, you can use the text to speech facade to make the droid speak:
Note: Tasker also supports SL4A scripting, so you can use that to monitor the system and launch Python programs whenever certain conditions are met.
The Wild West: Open Platform, No Docs
The raw API is fully documented, online. However there’s very little information about how to use it. There’s more information at the SL4A and PY4A project sites, but not nearly enough. Personally, I reckon open source devs are smart enough to know to never write documentation ~ that way, they can earn a living writing books…
The Apress book Pro Android Scripting with SL4A, by Paul Ferrill, really is an awesome resource for learning to use the Scripting Layer properly, and uses Python as the example language. Apress have also published Beginning Android Tablet Programming, by the SL4A project’s lead developer, Robbie Matthews. This is more focussed on tablets specifically, and less focussed on Python, but is still an excellent book from someone who really knows their subject.
There’s also the SL4A and PY4A Google Groups to look to for help. They can be a bit lonely, but if you word your question well, you’ll normally get a helpful reply before very long. There’s plenty of archived material there too.
This Python Central Series aims to cover all the most important things Python programmers need to know about Android and the Scripting Layer, to help you get up to speed. And, as always, we’d really appreciate the community’s input on our project, so if there’s anything you’d like to see, make sure you let us know about it.