Thumby: Kickstarter Getting Started Tutorial

Thumby: Kickstarter Getting Started Tutorial

 This tutorial will show you how to build a basic project and upload it to your Thumby using our online IDE!

NOTE: The Thumby IDE and accompanying tutorials will update as more features are added and as we grow our software support for Thumby during Kickstarter fulfillment. If you are interested in hearing software updates as they happen, consider joining our Discord. Thank you for your patience and support!

Tutorial Last updated: January 12th, 2022


Materials 

Hardware: 

    Software: 


    Using the Thumby IDE

    Open Google Chrome or Microsoft Edge and open the online Thumby IDE, the below screen will appear:

    Thumby web browser ide dark mode screenshot

    Figure 1: Screen on opening IDE for the first time

    If you prefer a light theme, hover over the 'Utilities' dropdown in the top bar and left-click 'Invert Theme'.

    Thumby web browser ide light mode screenshot

    Figure 2: Light theme

    As you get familiar with the Thumby Web IDE - hover over buttons to get tooltip information on what menus and buttons will do. 

    Connecting Thumby to the Web IDE:

    1. Turn your Thumby on (switch the top power switch to the right when looking at the screen), and connect it to your PC using a Micro USB Cable 

    • NOTE: Some Micro USB cables only include power and ground wires to power or charge devices - if you are having trouble connecting your Thumby in the following steps, try using a different USB cable. Test the USB cable you are using is able to transfer data by transferring files, like pictures or text files, from a different USB compatible device. 

    2. Click 'Connect Thumby' in the top bar

    3. Select the device through the pop-up menu

    4. Click 'Connect'

    The below screenshot shows the button locations and order to click them in.

     Step 2 of connecting thumby on web browser ide

    Steps 3 and 4 of connecting thumby using the web browser IDE

    Steps to connect Thumby

    If connection is successful, a green 'Connected' message will be printed to the terminal - you will also see a hardware icon appear at the right side of the browser tab to show that you are connected to a Serial port.
    Thumby Connected Screen
    Thumby Connection Screen
    After doing the above connection steps, the Thumby will be paired to the webpage and will auto-connect when 'Connect Thumby' is clicked.
    With the Thumby connected it is time to upload some code!

        The Code - Thumby Games!

            Follow the below steps to start a project and then upload it to Thumby.

            • Hover over the 'Utilities' menu and click 'Make New Game ', set the name to anything you like.

            Thumby IDE create a new game

            New game creation

            • Click 'OK' after typing in a name, in this case, we used: HelloWorld 

            The Thumby Filesystem should be preloaded with a 'Games' and 'lib' folder, each containing files. Double left-click any file to open it in a webpage code editor. 'thumby.py' in 'lib' is the main API that should be used to program your projects.

            After exploring any of the library or game files, close those editors by left-clicking the 'X' in the respective tab of the editor, see the pink arrow in the below image.

            Closing thumby editor tabs

            Closing any open editor tabs

            If you close all of the editors, or close out of any of the other Windows like the Shell or Emulator, you can reopen these windows by going to 'Utilities' -> 'Widgets' -> and then you can add back any window panel options. 

            Writing Your First Thumby Game

            Follow the below steps and enter code as you go to program your first Thumby project.

            • import the time and math modules that will be used for animating a sprite with respect to time. Also import the thumby module which implements the main API for interacting with buttons and the screen

            import time
            import thumby
            import math

            • Draw a Sprite:
              • Using the Bitmap Builder panel:
                • First, set the width and height to 32px by clicking the 'Size' button in the Bitmap Builder. Left-click bitmap squares to set pixels to black, and right-click squares to set them white
                • Once the sprite is drawn, select a line in the code editor added earlier, then click the 'Export Lines' button in the 'Bitmap Builder' panel - see the below image for the result.
                • NOTE: The Bitmap Builder will be deprecated in future Thumby Web Browser IDE versions.
              • Or you can draw a Sprite/Bitmap using a tool like GIMP - export btimaps as binary files (.bin) to include in your games.

            # BITMAP: width: 32, height: 32
            bitmap0 = bytearray([0,0,0,0,0,0,0,0,248,8,232,40,40,40,40,40,40,40,40,40,40,232,8,248,0,0,0,0,0,0,0,
            0,0,0,0,0,0,0,0,0,255,0,63,32,32,32,32,32,32,32,32,32,32,63,0,255,0,0,0,0,0,0,0,
            0,0,0,0,0,0,0,0,0,255,0,12,12,63,63,12,12,0,0,24,24,3,3,0,255,0,0,0,0,0,0,0,0,0,
            <emcode0,0,0,0,0,0,0,31,16,16,16,16,20,18,16,20,18,16,16,16,16,16,31,0,0,0,0,0,0,0,0])

            • Initialize the sprite object using the width, height, and bytearray object OR binary file location of the sprite:

            # Make a sprite object using bytearray (a path to binary file from 'IMPORT SPRITE' is also valid)
            thumbySprite = thumby.Sprite(32, 32, bitmap0)

            • Set the frame rate of the Thumby game to control how fast the screen changes:

            # Set the FPS (without this call, the default fps is 30)
            thumby.display.setFPS(60)

            Adding Game Logic to Move Sprites

            • Create a loop where the sprite will be animated bobbing up and down. The first steps every loop are to store the current time in milliseconds and to clear the screen to black:

            while(1):
                t0 = time.ticks_ms()   # Get the current time in milliseconds
                thumby.display.fill(0) # Fill canvas to black to make it 'blank' 

            • As time goes on create a vertical offset using the sin function. The offset will move the sprite up and down 5px.

                bobRate = 250 # How fast the animation is (higher is slower, arbitrary)
                bobRange = 5  # The range in pixels of the bob (how far it moves up/down, -5px to 5px)

                # Calculate number of pixels to offset sprite for bob animation
                bobOffset = math.sin(t0 / bobRate) * bobRange

            • Next, use the Thumby screen width and the width of the bitmap to center and calculate the sprite's X and Y location

             # Center the sprite using screen and bitmap dimensions and apply bob offset thumbySprite.x = int((thumby.display.width/2) - (32/2)) thumbySprite.y = int(round((thumby.display.height/2) - (32/2) + bobOffset))

            • The sprite is drawn on the screen, every loop, using the bitmap data array, the sprite X & Y position, and the sprite dimensions

                # Display the bitmap using bitmap data, position, and bitmap dimensions
            thumby.display.drawSprite(thumbySprite)
                thumby.display.update()

            That's it! You can emulate the project in the web browser by selection the red checkbox of the 'Emulation:' option in the Editor. Then press the 'Start' button in the Emulator window.

            Adding Your Game to Thumby

            For your project to show up on the Thumby game select screen, there needs to be one .py file with the same name as the project. Before clicking upload, the webpage and code should look something like the below image:

            Thumby IDE screenshot of file system and emulation

            Setup before clicking 'Upload Files'

            Now click the 'Upload Project' button on the top of the page, disconnect Thumby, power cycle it (turn off and on), use down on the Thumby dpad to find your project, click the left button to select and execute your main project file.

            If the above code was used, the below animation will play after selecting 'HelloWorld' in the Thumby select screen:

            Other Thumby tutorials:

            Other Webpage Features

            • Execute a single file on the Thumby at root level '/' using the 'Fast Execute' button in any code editor
            • Import/export a .py file from/to your computer using the file drop-down in any editor (left-click 'File')
            • Change the font size of individual editors using the view drop down (left-click 'View')
            • Delete files or directories on the Thumby by left-clicking in the Filesystem panel
            • Open files stored in Thumby by right-clicking in Filesystem panel
            • Reset page layout by re-positioning each panel using button under Utilities -> Reset Layout
            • Reset and erase all page memory using button under Utilities -> Hard Reset Page
            • Clear and invert buttons in the bitmap builder
            • Import exported lines to bitmap builder by selecting bitmap array and comment then left-clicking
            • Download most compatible/tested Thumby MicroPython firmware through Utilities -> Download Firmware button and follow instructions provided when hovering over 'Download Firmware' button
            • All work is automatically saved to the webpage, nothing is lost on a page refresh

            Contact Us

            If you have any questions or feedback, feel free to contact TinyCircuits support or make a post on the TinyCircuits forum.

            Show us what you make by tagging @TinyCircuits on Instagram, Twitter, or Facebook so we can feature it!

            Thanks for making with us!