Android Circuit Python Editor

Use a USB OTG cable with Android devices for Serial, REPL, and a basic code editor for use withCircuit Python Boards.

Similar projects worth following
It's an Android app that uses USB Serial to communicate with Circuit Python boards. You can use it to see the print() outputs for debugging, or enter the REPL to execute python commands on the board. Using the REPL we can read and write the and other files stored on the board that were inaccessible due to incompatible file storage system.

CircuitPython boards are great because they run python duh, but also because they are simple to use. You plug it in to a computer, it shows up as a small "thumb drive" type device that stores the .py file. You edit that file, save it and the board runs your new code, easy peasy.

But what if we want to take our Circuit Python development on the go with our Android phone or tablet? Lets grab an OTG cable and find out. Ah DRAT!! we get this nasty message about unsupported storage. It turns out the Circuit Python boards are using an older file format system (FAT12 maybe?) and Android does not seem to support this. 

Well shucks, I guess our hopes and dreams of mobile Circuit Python development are pretty well crushed aren't they?  Not so fast! could there be another way? 

Idea: Instead of using the board like a filesystem, we can connect via serial to the board and use the REPL to help us load and save python code.

If you are ready to dive in right away you can get the app from this Play Store link or scan this QR code: 

The easiest way to learn the ropes is with the Adafruit Learning System guide. Check it out to get started.

If you want to learn more about the application and how it came to be then read on here, and check out the project logs.

Luckily [felHR85] has created this super useful USB Serial library that we can use to get connected and communicating with the board. Once the communication was established then entering the REPL was pretty straight forward. To load the code we use REPL to open and dump it's contents into serial output so we can read it on the Android side. Saving proved to be a bit trickier, I ran into errors trying to write the entire file at once. Currently It's writing one line at a time, again using statements in the REPL. Once it's done you can send ctrl-D to reload and run your new code.

All of my testing thus far has been on Circuit Playground Express, but it should support other boards too. If you have direct knowledge of how it works (or doesn't) on other specific boards or with certain Android devices please feel free to share.

The Github linked in the project is for the Android app, there is a debug APK file in the repo if you just want to try out the app and don't have access to Play store. 

If you do use the application please let us know how it goes!

WARNING: This app is in the alpha stage, it may not work at all for you. Or worse it may work improperly and erase, or overwrite with non-sense the code on your board. Please keep an extra copy of any important code stored on your PC or somewhere other than the Circuit Python board. That way you can always remount to read-only and save your working code on the board using the standard file transfer method.

  • 1 × USB OTG Cable (probably)
  • 1 × Android Device
  • 1 × Circuit Python board STORAGE MOUNTED!!!

  • A pair of updates. Plus some testing on new boards.

    foamyguy12/22/2018 at 03:44 0 comments

    Up / Down buttons

    I started working a few days ago on a new feature for the terminal. Up and down buttons for cycling through history in the REPL. I found myself wanting this while playing around with the application. The board handles the bulk of the work to achieve this as long as we send it the character codes for up and down. However it did take a bit of tinkering to get terminal client behaving properly when sent ANSI codes like:


    I've never implemented a terminal client before so this was new territory for me. I've got it to a point where it's working pretty well I think tonight so I made a new release with the new buttons. The biggest challenge with this proved to be alling the historical command to be edited. Since the REPL stores internally the current command as you are cycling through we need to let it know if the user edits the command before sending it. I tried using some other ANSI codes to solve this problem, but had no luck that way. I'm not sure if I have a full enough grasp on those yet. To get it working it will silently send backspaces to erase the internally stored command prompt, but still allow the user to edit it in the edit text. Once the user presses send the prompt is empty and the newly edited (or not) command is sent.

    Newline error in the editor

    After the new release was ready and uploaded I was playing around a bit more testing out a few new boards (more on that later). I noticed that the code editor was broken when trying to add newlines to the code file. The newlines were not getting written properly, which caused to get malformed. 

    The fix was relatively quick to get working and I believe all is well now. Hopefully this didn't bite anyone else before it was fixed. 

    The newest build including both the up/down buttons and the newline editor fix is live now on the Play Store, and a new debug apk has been checked in to the repo.

    Additional boards tested (Itsybitsy M4, Feather M4)

    As noted elsewhere in the project it should work for all CircuitPython boards, but all of the testing and development was done on a Circuit Playground Express. I finally opened up some of the new M4 boards that have been awaiting testing. Happy to report no issues found so far on the ItsyBitsy or the Feather. You do of course need to edit your to mount the storage if you want to use the code editor, and neither of these boards has an on board switch so it's not quite as convenient as the CPX. The Feather has a bit of proto board that would fit a small switch nicely though if you wanted. If you're using a board with no hardware switch one thing I've found helpful is creating a REPL macro to rename the file to so it won't run, and therefore the storage will remain ready for standard USB file transfer.

    If you know of other boards that are for sure working (or not) please drop a comment to let us know.

    That's it for this update. Enjoy that sweet REPL history. I'm very sorry if I wrecked your file with newlines.

  • Adafruit Guide

    foamyguy12/18/2018 at 23:56 0 comments

    Shortly after posting this project our friends at Adafruit found it and got in touch with me. They asked if I'd write a guide that covers the usage of this application for publishing on I am happy to announce that the guide is now finished and live! You can find it here: and I've added it to the project links. Big thanks to Adafruit for the opportunity.

  • New version and REPL macro musings

    foamyguy12/18/2018 at 04:12 0 comments

    There is a new build live in the Play Store, and a debug signed copy has been updated in the repo. This version brings some more improved error handling. Now if you try to do some action (load, save, run macro) and are in the wrong mode it will prompt you with a dialog that has the option to send the the correct CTRL key without leaving the page.

    I think at this point we've reached what I'd consider a pretty good version of everything I had originally envisioned when I set out to create this app. I will keep using the app and look for ways to improve but I have nothing else specifically in mind. If you have ideas for this app please feel free to share!

    REPL macros

    This feature was honestly a bit of surprise to me. I did not really think of this concept until after the basics of the app were already working. It was a natural extension of what the app uses internally to load and save the file. 

    The core concept here is: create and store files with python code in them. Whenever you are ready to execute it, send it into the REPL line by line rather than saving it to and then restarting the board. 

    This is an interesting way to use CircuitPython, it's grown on me quite a bit I must say. 

    It's "temporary" in that it doesn't overwrite the file so if your board is set up to do whatever it is doing in your project you can leave that in place but still execute some other useful code perhaps related, to the project, or maybe not even, maybe you're warm and just want to send an IR blast to turn on the fan.

    The files are stored on the computer (or Android device in our case) instead of the board so we aren't really limited by storage size. You could conceivably keep a large library organized into sub-folders and everything then pull out the proper script and use it as needed.

    It's QUICK! If you've already got your code ready to go you can rapidly switch between different programs running on the board. It makes it possible to demonstrate a few different features or neat things that you can do with a Circuit Playground (or CircuitPython in general) in just a few seconds. Once you've shown them the effect you can also dive in and show the code that drives it.

  • Launch Party!

    foamyguy12/14/2018 at 14:26 0 comments

    The app is now live in the Android Market! If you were wanting to try out this application, but for whatever reason didn't want to download the apk from Github and side load it then today is your lucky day.

    You can download it from the play store using this link:  Play Store Link. Or if you have a Barcode Scanner you can scan the QR below to open up the Play Store.

  • Fancy new build

    foamyguy12/13/2018 at 04:31 0 comments

    The time has come. The new build is ready enough to share more properly. The new APK file is in the repo. This build brings the REPL macros from the previous log as well as a few other improvements. There is now a title bar with shortcuts to each utility along the top. I've made the wrong mode failure cases behave a bit nicer. I've also added some resiliency to spamming on load and save buttons on the editor page. Oh and the terminal text is now selectable for copy/paste.

    I think it's almost nearly ready for the first release on the play store. Just need to clean up a few more things.

  • REPL Macros

    foamyguy12/10/2018 at 04:30 0 comments

    The most recent commit to the repo begins the implementation of a new feature that I am quite excited about. I've added a list of macros that can be saved in your phone and then executed whenever you want at the click of a button. 

    To access the macros long press on the serial text output (make sure you enter REPL first!) after you long press you'll see a list of your existing macros (none by default). You can create a new macro, and choose a name for it. Once it's in the list you can edit the macro and add some code to it. Press the save button to save the macro file to the internal storage in your phone. Press the run button on a macro to execute it in the REPL.

    I've not updated the APK in the repo yet, so if you want a sneak peak of this feature you'll have to clone the repo and built the app yourself. Once the user interface is a bit better and some more of the kinks are ironed out I'll make a new APK for the repo. 

    Also we should be launching with a version on the Play Store soon so it will be easier to install the app for new users.

  • How we got to here. A brief history.

    foamyguy12/09/2018 at 04:04 0 comments

    For a project at work I recently deployed a few hundred Circuit Python boards that were embedded as one component within a larger system.

    As part of planning for this we thought about the question: "What if we find a problem with the python code after the boards are already deployed?" We started looking into ways to update the code on the board. Our system includes an Android device that the Circuit Python board is plugged in to. For a while we assumed USB Storage would work, but once we got around to testing it out we realized that it didn't. As those pesky real-world projects tend to this one came with a tight deadline, so we had to drop it and move on to other things to get that project completed. 

    Once we got everything shipped out and things slowed down a bit I got to tinkering with the Circuit Python boards a bit more. I played around with the serial connection and REPL a bit and starting thinking maybe this was a better avenue to interact with the board on Android.

    The first real world test was USB Terminal program from the Play Store. I loaded it up and was able to see print() outputs from a Circuit Playground Express. Next up was testing the CTRL keys, which is no trivial task on a mobile phone. It turns out there are also keyboards that include CTRL keys on the Play Store so I got one of those installed/enabled/set as my keyboard. Sure enough sending CTRL-D and CTRL-C worked correctly when I sent them via the terminal program using the special keyboard. As the final proof of concept test I used the terminal program to enter the REPL and save hello world to After a quick detour figuring out the storage mounting it was working perfectly. At this point I knew what I wanted to do was possible I just needed to bring it all together into my own app. The idea gets shelved for a bit here waiting to get pulled out again next time we have a bunch of boards getting shipped out.

    Around the holidays though I got to thinking about using this idea for something outside of the work deployment. I was looking for a way to bring Circuit Playground boards with me to family gatherings and show them to the kids and teach them about the board and how to make it do neat things. I could bring a laptop but then I've got to lug that around and get it out plus pack it away after, I didn't want the hassle. I could use a battery pack, but then I can't really show the code or change it to do much different stuff especially things that the person being shown suggests. So the thought is maybe I can use the USB Serial idea from before but make the app into more of a basic IDE that can edit and run code and use the REPL. 

    I did not quite get it working in time, but there are more holidays right around the corner so I'll be ready for those. Plus I can use my phone to reprogram the Circuit Playground ornament hanging on the Christmas tree.

  • Tab your way to completion

    foamyguy12/08/2018 at 04:08 0 comments

    Github user [alanjds] opened an issue asking to add a Tab button to the application for use with REPL. I didn't even know that the REPL offered tab completion before that. It was pretty straight forward to add a tab button and right away I could tell that it was possible to make it work because it was able to make suggestions about what I had typed. But to use it effectively was bit more tricky because sometimes it returns full strings and other times it only returns the ending part of the string, and other times it returns lists of available strings, so the app needs to behave correctly in all these cases. In the end I settled on reading the string out of the display text box. It's working pretty well but there are still some scenarios where the behavior is not great.

    If you want to give it a try the debug apk in the repo has been updated to the new versions. Let me know how it goes if you do!

  • USB Serial Library

    foamyguy12/01/2018 at 17:56 0 comments

    The app uses this library for USB serial communication:

    It comes in synchronous and asynchronous flavors . I've tried both but had better luck with the asynchronous overall so far. The downside is that flow control doesn't seem to be working so we have to have an artificial delay between commands or else sometimes they get spliced together on subsequent writes to the serial port. In the end I need to either work out the synchronous controller, or else figure out how to get flow control working, that would speed up, perhaps considerably, the time it takes to save code back to the board. Another option to explore is writing more than one line at a time. I had trouble with writing the full file at once, but I suspect chunks larger than a single line are possible.

View all 9 project logs

  • 1
    Mount the storage as writable

    Your circuit python board must have the storage mounted as writable in order for the save function in our editor to work. Serial, REPL, and loading code do not require this, but if you want to save the code back to the board it must be mounted. See details here: I've found it useful to have my script check the on-board switch and set the mode accordingly. Here is the code from my, you'll need to tweak it if you aren't using a Circuit Playground Express.

    import board
    import digitalio
    import storage
    switch = digitalio.DigitalInOut(board.D7)
    switch.direction = digitalio.Direction.INPUT
    switch.pull = digitalio.Pull.UP
    # If the switch is flipped
    # CircuitPython can write to the drive
    storage.remount("/", switch.value)

     Since only runs when the board powers on you must flip the switch while it's unpowered, then plug it in for the mounting to take effect.

View all instructions

Enjoy this project?



Barbudor wrote 02/03/2019 at 10:55 point

Hi FoamyGuy

Really nice app. I have used with an Adafruit CPX and it is working great.

I was wondering as I'm moving to some other Python based boards (ESP8266 ), would it be possible to allow your app to work with any board which provide REPL over USB CDC serial ?


Best regards

  Are you sure? yes | no

foamyguy wrote 02/03/2019 at 15:18 point

It should be possible. But unfortunately I haven't had much luck yet. I've tried the Pyboard 1.1 and the Micro:Bit and neither have worked correctly. It seems there is something inhibiting the serial connection partially with those boards. I haven't tried with any of the ESP based boards though. 

  Are you sure? yes | no

Barbudor wrote 02/03/2019 at 17:40 point

I just tried the "USB RS232 BT SPP Wi-Fi TCP UDP Color Terminal Demo" Android app (yes that's the name ;) )and I can connect to the REPL console.

Depending on the board, USB serial chip is either a CP2102 or a CH340G.

If you ever look to make a beta, let me know, I will be happy to test :D

  Are you sure? yes | no

Luc wrote 12/04/2018 at 13:29 point

What is that round device with the knob???

  Are you sure? yes | no

foamyguy wrote 12/04/2018 at 17:42 point

That is another one of my projects that is unrelated to the Android app. It's a cheap electronic toy game "Bop It" with the guts removed and replaced with a Circuit Playground. It will eventually get it's own project page on here, so if you are interested in it be sure to check back for that.

  Are you sure? yes | no

Similar Projects

Does this project spark your interest?

Become a member to follow this project and never miss any updates