This article is part 1 of 3 in the series Python Android Scripting Layer (SL4A) Tutorial

Last Updated: Thursday 12th December 2013

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.

Currently, the Scripting Layer supports Python, Perl, Ruby, Lua, BeanShell, JavaScript and Tcl. It also provides access to the Android system shell, which is actually just a minimal Linux shell.

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.

This series focuses on Python, and Python is the most popular and well supported language on SL4A, but the other languages have features which can be really useful. For example, BeanShell, which is a very high level language that compiles to Java, has the ability to side-step the Scripting Layer API and access the Android Java API directly. The Scripting Layer's Ruby and JavaScript interpreters, JRuby and Rhino, also run on the JVM, so these languages can do this too. It's nice to have an environment with these kinds of features available.

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 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.

About The Author

  • Gabriel Pettier

    Hey, just want to point out this is slightly wrong.

    «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.»

    We have something called “pyjnius” (http://github.com/kivy/pyjnuis) that allows to access java classes from python, it’s not itself specific to android (it will work on desktop too), but it works there well, you can use the “autoclass” function to get a python wrapping of a java class, and use it to call the android api directly, it’s not perfect, but it gives you access to a vast part of the android api, with much flexibility, much more than predefined wrappings like SL4A can provide. Have a look at the examples on http://pyjnius.rtfd.org/. You can create false java class from python, implementing the required interfaces to pass them to android callbacks too, the last limitation we have is inheritance, we can’t extend a java class from python yet, we still hope to find a solution for that soon, but SL4A can’t do this either. You can do a java class and use it from kivy/pyjnius if you need to do that.

    Whatever solution you chose, have fun doing python on android.

    • Carl Smith

      Thanks for your input Gabriel. I’d seen pyjnius, but it was really early days on the project, and it had a long way to go. It sounds like you’ve got it together now. I’ll take some time out this evening to look into it more, and check out those examples.

      Cheers

      • Carl Smith

        I had another look at pyjnius, and it still seems to have long way to go.

        You can already call the Android API from SL4A directly, just not from Python. You could do it with a few other languages that are supported, and extending the SL4A API is easy enough too, if you want to play with Java.

        Kivy is nice when you’re building full blown, multi-platform, quasi-native applications, but it just doesn’t give you Python on Android, in the sense that it doesn’t let me write a script in Python and run it on Android. I have to build some massive APK on a machine running something other than Android, then install the APK on an Android device, or run it in an emulator, and I’m not sure what such an app can do that an SL4A based app can’t??

        • Ronnie Andrew Magatti

          I’ve used SL4A and Kivy, in my opinion at the same time that they seek different goals they could complete each other.
          Accessing hardware with SL4A is surprisingly easy, and you want to run scripts its the best choise, but using Kivy instead of webviews to build nice GUIs is a very good option!
          I have also used Pyjnius, and recognize that it is very useful for some things like in my case: playing an online mp3 stream from my Kivy app.

          The point is, if only i could use both these projects together it would be the perfect Python for android development setup.

          Although they are meant to serve different purposes, we shouldn’t be arguing about what one can do that the other can’t. We should be arguing about how to make these two amazing projects complete themselves.

  • Rolando Rolon

    I must say that this project is one of the best i’ve kown about in a long while. Unfortunately, you can only use it if already a programmer and I thought it would be great for people learning Python but that’s not the case. Still a great job so i will surely use it a lot once i get a good grasp on Python. Don’t have anything useful to append to the subjet, I’m just writting because I felt I ought to thank the devs for this cool stuff. Greetings from Argentina.