Difference between revisions of "Getting started"

From Gamebuino Wiki
Jump to: navigation, search
(I added instructions for Linux users.)
(Add link to MAKERbuino build guide)
 
(35 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
== Get a Gamebuino ==
 
== Get a Gamebuino ==
  
For an overall presentation head to the [http://gamebuino.com home page] or [https://www.indiegogo.com/projects/gamebuino-an-arduino-handheld-console/x/6587762 indiegogo page].
+
To order a Gamebuino along with some cool customization accessories, head to the [http://gamebuino.com/shop Gamebuino Shop].
  
As the indiegogo campaign is over, you can't order a Gamebuino for now. But you can subscribe to the newsletter to know when they'll be available for order again.
+
While you wait for your Gamebuino to arrive, you can start to play and program games using one of the [[Emulators]].
 +
 
 +
== MAKERbuino build guide ==
 +
If you got a MAKERbuino kit and wonder how to assemble it, head to the [[MAKERbuino: build guide]].
  
 
== Use your Gamebuino ==
 
== Use your Gamebuino ==
Line 9: Line 12:
  
 
=== Turn it on ===
 
=== Turn it on ===
* You just received your Gamebuino. Hurray! You should first turn it on to check that nothing has been damaged during shipping. If nothing shows up the battery may be empty or the screen may have moved.
+
You just received your Gamebuino. Hurray! You should first turn it on to check that nothing has been damaged during shipping. If nothing shows up the battery may be empty or the screen may have moved... don't panic, and head to the [[troubleshooting]] page.
  
 
=== Load games from the micro SD card ===
 
=== Load games from the micro SD card ===
[[File:Micro sd loader title screen.jpg|right]]
+
<youtube>DCkUAPv2Cos</youtube>
* Make sure that the provided SD card is correctly inserted in its socket.
+
* The new graphical loader allows you to navigate through games easily. You can select a game, see it's description (use up and down arrows to browse through the description), delete saved games, or delete the game itself.
* The game browser is named LOADER.HEX. There are several ways to load it:
+
* To get back to the loader from a game, press "C" when in the game's main menu.
** Hold down C while you turn the power switch on then release it.
+
* For it to work, the micro SD card needs to be inserted, to be formatted to FAT, and to contain at least the file LOADER.HEX. See [[Troubleshooting#SD_card]]
** Press C in the Gamebuino title screen
+
* '''Pro Tip:''' If you accidentally turn the Gamebuino off while a game is loading, it won't start again. To solve this: hold "C" down, turn the Gamebuino ON, release "C", and wait 30 seconds for LOADER.HEX to be loaded from the SD card. You can also use this if you are stuck in a game which doesn't allow you to get back to the loader.
* '''Note:''' You should always get back to the title screen of the game and press 'C' to flash the loader before you turn your Gamebuino off, load another program through USB, or eject the micro SD card. It will avoid to mess up your saved games, as the EEPROM is backed up in a .SAV file when you switch from a game to the loader, and restored when you select a game from the loader.
 
  
=== Change the default settings ===
+
=== Adjust settings ===
[[File:Settings title screen.jpg|right]]
+
* When in the loader, select SETTINGS:
* Load SETTINGS.HEX
+
[[File:SettingsLogo.png]]
* Select "See all settings" to know what can be adjusted. These settings are stored directly in the Gamebuino and will be shared between different games.
+
* Useful settings:
* You should adjust these two settings at least:
+
** Default username in "change settings/player name"
** Display contrast
+
** Display contrast in "change settings/display/contrast"
** Default username
+
** Disable the critical battery alert by setting it to 0 in "change settings/battery/critic voltage"
* You can leave the other settings at their default value, it should be okay.
+
** Mute sound by default by setting "sound/default volume" to 0.
* Don't forget to select "save" before you exit.
+
* Don't forget to select "save" before you exit!'''
  
 
=== Charge the battery ===
 
=== Charge the battery ===
* You may want to charge your Gamebuino's battery when you receive it.
+
Simply plug in a micro USB cable (or smartphone charger).
* To load the battery, you just have to connect your Gamebuino to an USB port (from your computer or an outlet charger) using the provided micro USB cable. The "charging" LED will turn on (the one beneath the lightning bolt battery symbol) until it's fully charged. Then, the "charged" LED will turn on (the one beneath to the full battery symbol).
+
A full charge will give you up to 24 hours of play time... enough to beat your Tetris highscore!
* Your Gamebuino will charge faster if turned off.
+
 
* A charged battery will give you at least 8 hours of continuous play.
+
'''Pro Tip:''' Charge your Gamebuino from time to time, or the battery will die over a few months.
 +
 
 +
== Software setup ==
 +
 
 +
=== Install Arduino ===
 +
 
 +
* Download and install Arduino from [http://arduino.cc/en/Main/Software here].
 +
* Arduino 1.0.5 or above required. Arduino 1.6.2 or above recommended, it will make the library installation easier.
 +
 
 +
=== Install the Gamebuino Library (Automatic) ===
 +
'''For Arduino version 1.6.2 and newer.'''
 +
 
 +
Open the library manager:
  
=== Remove the paper cover ===
+
[[File:Arduino manage libraries....png]]
[[File:Remove paper cover.jpg]]
 
* The transparent acrylic case is covered with a brown paper protection. Some people may want to keep it, some may want to remove it.
 
* First, check that your Gamebuino works fine.
 
* Dismantle it:
 
** Unscrew the 4 short screws on the back side first
 
** Remove the back plate
 
** Unscrew the 4 white nylon spacers
 
** Remove the PCB
 
** Unscrew the 4 long screws on the front side last
 
* Remove the paper cover. Be careful not to scratch the acrylic
 
* Check that everything still works fine (especially the display)
 
* Assemble back your Gamebuino:
 
** Be gentle when you tighten the screws or you may damage the nylon spacers
 
** Screw the 4 long screws with 4 nylon spacers on the top plate (be careful to put it on the right side)
 
** Put the screen holder on the two upper nylon spacer
 
** Put the PCB in place, check that buttons are correctly placed int their holes
 
** Screw 4 nylon spacer to hold the PCB in place
 
** Add the back plate and screw it with the 4 short screws
 
** You might want to add a spacer between the back plate and the PCB to limit the PCB bending because of screen pressure
 
  
== Upload a program through USB ==
 
  
=== Install the Arduino software ===
+
Type "Gamebuino" in the search field, select the Gamebuino library and click "install":
  
* Download the Arduino application [http://arduino.cc/en/Main/Software here] and follow instructions to install it.
+
[[File:Arduino library manager gamebuino.PNG]]
* If you're using Windows, you may want to use the [http://forum.arduino.cc/index.php?topic=118440.0 Arduino Enhanced Release].
 
* '''Note''': If you are using a package manager to install Arduino, make sure it installs Arduino 1.0.5 (version 1.0 won't work).
 
  
=== Install the Gamebuino Library ===
+
Now '''restart Arduino''', and the Gamebuino examples will show up. Give it a look!
  
* Download and the [https://github.com/Rodot/Gamebuino/archive/master.zip Gamebuino library]
+
[[File:Arduino examples menu.png]]
* Extract the archive
 
* Mac users: you can follow this [http://gamebuino.com/forum/viewtopic.php?f=12&t=875&p=3501#p3501 video tutorial].
 
* Copy the folders "Gamebuino" and "tinyFat" located in /libraries and paste them in /Arduino/libraries (where you installed Arduino). On Mac: Put them in documents/Arduino/libraries
 
*'''Note:''' On Linux, you may have to open the terminal and use the command "sudo chmod -R ugo+rw /usr/share/arduino" before you can put the libraries or bootloader in their respective places in /usr/share/arduino.
 
* Copy the folder "gamebuino_boot" from the archive to /Arduino/hardware/arduino/bootloaders. On Mac: Right-click the Arduino-Application in your Programs-folder. Select "Show package contents", then search in this folder for "bootloaders" and copy the folder there.
 
* To check that the library is correctly installed, start the Arduino software, and click on File/Examples, you should find "Gamebuino".
 
  
=== Add Gamebuino to boards.txt ===
 
  
* Navigate to the folder where you installed Arduino
+
=== Install the Gamebuino Library (Manual) ===
* Open Arduino/hardware/arduino/boards.txt
+
'''For Arduino version pre-1.6.2.'''
* Add the following at the beginning of the file and save it
+
* Download and the Gamebuino library [https://github.com/Rodot/Gamebuino/archive/master.zip here] and extract it (see [[download]] page for more).
 +
* Put all the files in <sketchbook>/library/Gamebuino/
 +
** Windows: Documents/Arduino/library/Gamebuino/
 +
** OS X and Linux: <home>/scketchbook/library/Gamebuino/
 +
** You can change the sketchbook location in Arduino preferences: File/Preferences/Sketchbook location (requires a restart).
 +
* '''Restart Arduino''' and click on File/Examples/Gamebuino. If Gamebuino is not there, check that the library is in the right location and restart Arduino.
  
<pre>
+
=== Install the Gamebuino board ===
  
##############################################################
+
COMING SOON: Arduino board manager compatibiliy.
gamebuino.name=Gamebuino
 
gamebuino.upload.tool=avrdude
 
gamebuino.upload.protocol=arduino
 
gamebuino.upload.maximum_size=30592
 
gamebuino.upload.maximum_ram_size=2048
 
gamebuino.upload.speed=115200
 
gamebuino.bootloader.low_fuses=0xff
 
gamebuino.bootloader.high_fuses=0xda
 
gamebuino.bootloader.extended_fuses=0x05
 
gamebuino.bootloader.path=gamebuino_boot
 
gamebuino.bootloader.file=gamebuino_boot.hex
 
gamebuino.bootloader.unlock_bits=0x3F
 
gamebuino.bootloader.lock_bits=0x0F
 
gamebuino.build.mcu=atmega328p
 
gamebuino.build.f_cpu=16000000L
 
gamebuino.build.core=arduino
 
gamebuino.build.variant=standard
 
##############################################################
 
  
</pre>
+
=== Select the board ===
* Restart the Arduino Software
+
For a quick start, select '''Tools/Board/Arduino Uno''', then select '''Tools/Processor/ATmega328'''.
* Now you should be able to set the device to Gamebuino by selecting Tools/boards/Gamebuino in the menu bar.
 
  
 
=== Install the drivers ===
 
=== Install the drivers ===
  
* Note: your Gamebuino should be turned on when you connect it to the computer
+
If you need help installing the drivers, refer to [http://arduino.cc/en/Guide/HomePage the Arduino guide] ([http://arduino.cc/en/Guide/Windows#toc4 Windows], [http://arduino.cc/en/Guide/MacOSX#toc3 MacOSX], [http://playground.arduino.cc/Learning/Linux Linux]). Note that your Gamebuino should be turned on when you connect it to the computer
* Note: drivers should be installed automatically on Windows if you used the installer
 
* Drivers are located in the Arduino/drivers folder
 
* If you need help installing the drivers, refer to [http://arduino.cc/en/Guide/HomePage the Arduino guide]
 
  
=== Upload a game ===
+
== Upload a game through USB ==
  
* Start the Arduino software
+
* Start Arduino
* Open an example by clicking File/Examples/Gamebuino/ If you don't find it, check that you correctly installed the Gamebuino library
+
* Open an example: File/Examples/Gamebuino/
* Select the right device by selecting Tools/boards/Gamebuino
+
* Select the right device: Tools/boards/ (you can either choose Gamebuino or Arduino Uno).
* Select the right serial port in Tools/Serial Port. If it's grayed out check that you have correctly installed the drivers, that your Gamebuino is turned on, and that the cable is working and correctly plugged in.
+
* Select the serial port: Tools/Serial Port/
* Click on "Upload" or press Ctrl+U
+
** If it's grayed out check the drivers, your USB cable, and that the Gamebuino is ON.
 +
* Click on "Upload"
 +
** Pro Tip: press Ctrl+U instead
 +
 
 +
'''You just uploaded your first Gamebuino game, congratulations !'''
  
You just uploaded your first Gamebuino game, congratulations !
+
'''Pro Tip:''' You can use one of the [[Emulators]] during development, rather than using the USB upload, this will allow faster development. Once you're done put the HEX file on the SD card (see below) and play your game for real on your Gamebuino!
  
 
== Put games on the micro SD card ==
 
== Put games on the micro SD card ==
* Game files which can be loaded on the Gamebuino from the SD card are .HEX files.
+
=== Get an .HEX ===
* You can get .HEX files of the default programs on [https://github.com/Rodot/Gamebuino GitHub], and .HEX file of other people's games in the forum in the [http://gamebuino.com/forum/viewforum.php?f=17 Games Gallery].
+
You need a compiled game in the .HEX format on the micro SD card to be able to play them on your console. <code>.HEX</code> can also be played on a computer using the Simbuino emulator (see [[Download]]).
=== Get the .HEX file from your game ===
+
 
 +
You can get a compilation of the necessary <code>.HEX</code> files (<code>LOADER.HEX</code> and <code>SETTINGS.HEX</code>) along with up-to-date games here: [https://github.com/Rodot/Gamebuino-Games-Compilation Gamebuino-Games-Compilation].
 +
 
 +
Browse all the games created by the community by visiting the [[Games]] Gallery.
 +
 
 +
=== Make your own .HEX ===
 
* Start the Arduino software
 
* Start the Arduino software
 
* Click on File/Preferences and check "Show verbose output during compilation"
 
* Click on File/Preferences and check "Show verbose output during compilation"
 
* Compile your program (Ctrl+R)
 
* Compile your program (Ctrl+R)
* A lot of text will scroll in the black area at the bottom of the window
+
* A lot of text will scroll in the black area at the bottom of the window. The build directory path will be displayed there, and should looke something like:
* Find the build directory for your program:
+
** Windows: <code>"C:\Users\Username\AppData\Local\Temp\build[random number].tmp\a_Hello.cpp.hex"</code>.
** Windows: <code>"C:\Users\Username\AppData\Local\Temp\build[random number].tmp\a_Hello.cpp.hex"</code>
 
 
** GNU/Linux: <code>"/tmp/build[random number].tmp/a_Hello.cpp.hex"</code>
 
** GNU/Linux: <code>"/tmp/build[random number].tmp/a_Hello.cpp.hex"</code>
* '''Note:''' If you use the [http://forum.arduino.cc/index.php?topic=118440.0 Arduino Enhanced Release], just press Ctrl+Alt+R to open the current build folder.
+
** Mac : Type <code>open $TMPDIR</code> in your mac's terminal to open the folder that is otherwise not accessible. You can then make a shortcut to your desktop.
 +
* You can also change the build path in <code>"arduino/lib/preferences.txt"</code> by changing the line <code>#build.path=</code> to <code>build.path=(directory you want)</code>.
 
* Navigate to this folder and find the .hex file with the name of your program
 
* Navigate to this folder and find the .hex file with the name of your program
 
* Rename it to a 8:3 format: only capitals, 8 characters max for the name and .HEX extension. For example: CRABATOR.HEX or PONG.HEX
 
* Rename it to a 8:3 format: only capitals, 8 characters max for the name and .HEX extension. For example: CRABATOR.HEX or PONG.HEX
  
 
=== Put it on the micro SD card ===
 
=== Put it on the micro SD card ===
* Put that file on your micro SD card using the micro SD adapter provided.
+
Put your .HEX file with a 8:3 name on your micro SD card using any micro SD card reader. You can now select the .HEX file on your Gamebuino to load it on the go, without a computer! Do '''NOT''' turn off your Gamebuino while flashing.
* You're ready to go!
 
  
== How to make your own games ==
+
=== Add a logo and description ===
* If you never programmed before, you should read the [http://arduino.cc/en/Tutorial/Foundations Arduino Foundations] page to understand... foundations.
+
[[File:InfEncoderScreenshot.png|right]]
* You should explore the basic [[Examples]], try to understand them, change things an see what happens. There is a lot of comments in the examples, so it should be easy to understand. If there is something you don't get, take a look at the [http://arduino.cc/en/Reference/HomePage Arduino Reference] for general purpose things, and the Gamebuino [[Reference]] for Gamebuino-specific functions. Open the examples in the Arduino software by clicking File/Examples/Gamebuino/basics.
+
If you want your game to appear with a logo and description in the loader, you have to create an .INF file and put it along the .HEX file on the SD card.
 +
* Get the INF encoder from the [[Download]] page (requires Java).
 +
* Put the generated .INF file along with the game's .HEX file on the SD card. They must have the same name, all in capitals, and 8 characters max. For example CRABATOR.HEX (the game binaries) and CRABATOR.INF (the description file).
 +
* Logo must be 19*18px
 +
* Slides must be 84*32px, up to 255 slides is allowed.
 +
* Drag and drop slides to reorganize them
 +
* The first slide is the one shown while the game is loading
 +
* Slides can be used to describe the game, tell the story, explain how to play, etc. By putting this information in the INF you can read it before loading the game, everything that's in the .INF don't need to be in the .HEX so it frees some space for your code.
  
 
== See Also ==
 
== See Also ==
* [[Reference]]
+
* [[Troubleshooting]]
* [[Examples]]
+
* [[Learning]]
* [https://github.com/Rodot/Gamebuino Gamebuino on Github]
+
* [[Games]]

Latest revision as of 2017-01-01T18:31:38

Get a Gamebuino

To order a Gamebuino along with some cool customization accessories, head to the Gamebuino Shop.

While you wait for your Gamebuino to arrive, you can start to play and program games using one of the Emulators.

MAKERbuino build guide

If you got a MAKERbuino kit and wonder how to assemble it, head to the MAKERbuino: build guide.

Use your Gamebuino

Error creating thumbnail: Unable to save thumbnail to destination

Turn it on

You just received your Gamebuino. Hurray! You should first turn it on to check that nothing has been damaged during shipping. If nothing shows up the battery may be empty or the screen may have moved... don't panic, and head to the troubleshooting page.

Load games from the micro SD card

  • The new graphical loader allows you to navigate through games easily. You can select a game, see it's description (use up and down arrows to browse through the description), delete saved games, or delete the game itself.
  • To get back to the loader from a game, press "C" when in the game's main menu.
  • For it to work, the micro SD card needs to be inserted, to be formatted to FAT, and to contain at least the file LOADER.HEX. See Troubleshooting#SD_card
  • Pro Tip: If you accidentally turn the Gamebuino off while a game is loading, it won't start again. To solve this: hold "C" down, turn the Gamebuino ON, release "C", and wait 30 seconds for LOADER.HEX to be loaded from the SD card. You can also use this if you are stuck in a game which doesn't allow you to get back to the loader.

Adjust settings

  • When in the loader, select SETTINGS:
Error creating thumbnail: Unable to save thumbnail to destination
  • Useful settings:
    • Default username in "change settings/player name"
    • Display contrast in "change settings/display/contrast"
    • Disable the critical battery alert by setting it to 0 in "change settings/battery/critic voltage"
    • Mute sound by default by setting "sound/default volume" to 0.
  • Don't forget to select "save" before you exit!

Charge the battery

Simply plug in a micro USB cable (or smartphone charger). A full charge will give you up to 24 hours of play time... enough to beat your Tetris highscore!

Pro Tip: Charge your Gamebuino from time to time, or the battery will die over a few months.

Software setup

Install Arduino

  • Download and install Arduino from here.
  • Arduino 1.0.5 or above required. Arduino 1.6.2 or above recommended, it will make the library installation easier.

Install the Gamebuino Library (Automatic)

For Arduino version 1.6.2 and newer.

Open the library manager:

Error creating thumbnail: Unable to save thumbnail to destination


Type "Gamebuino" in the search field, select the Gamebuino library and click "install":

Error creating thumbnail: Unable to save thumbnail to destination

Now restart Arduino, and the Gamebuino examples will show up. Give it a look!

Error creating thumbnail: Unable to save thumbnail to destination


Install the Gamebuino Library (Manual)

For Arduino version pre-1.6.2.

  • Download and the Gamebuino library here and extract it (see download page for more).
  • Put all the files in <sketchbook>/library/Gamebuino/
    • Windows: Documents/Arduino/library/Gamebuino/
    • OS X and Linux: <home>/scketchbook/library/Gamebuino/
    • You can change the sketchbook location in Arduino preferences: File/Preferences/Sketchbook location (requires a restart).
  • Restart Arduino and click on File/Examples/Gamebuino. If Gamebuino is not there, check that the library is in the right location and restart Arduino.

Install the Gamebuino board

COMING SOON: Arduino board manager compatibiliy.

Select the board

For a quick start, select Tools/Board/Arduino Uno, then select Tools/Processor/ATmega328.

Install the drivers

If you need help installing the drivers, refer to the Arduino guide (Windows, MacOSX, Linux). Note that your Gamebuino should be turned on when you connect it to the computer

Upload a game through USB

  • Start Arduino
  • Open an example: File/Examples/Gamebuino/
  • Select the right device: Tools/boards/ (you can either choose Gamebuino or Arduino Uno).
  • Select the serial port: Tools/Serial Port/
    • If it's grayed out check the drivers, your USB cable, and that the Gamebuino is ON.
  • Click on "Upload"
    • Pro Tip: press Ctrl+U instead

You just uploaded your first Gamebuino game, congratulations !

Pro Tip: You can use one of the Emulators during development, rather than using the USB upload, this will allow faster development. Once you're done put the HEX file on the SD card (see below) and play your game for real on your Gamebuino!

Put games on the micro SD card

Get an .HEX

You need a compiled game in the .HEX format on the micro SD card to be able to play them on your console. .HEX can also be played on a computer using the Simbuino emulator (see Download).

You can get a compilation of the necessary .HEX files (LOADER.HEX and SETTINGS.HEX) along with up-to-date games here: Gamebuino-Games-Compilation.

Browse all the games created by the community by visiting the Games Gallery.

Make your own .HEX

  • Start the Arduino software
  • Click on File/Preferences and check "Show verbose output during compilation"
  • Compile your program (Ctrl+R)
  • A lot of text will scroll in the black area at the bottom of the window. The build directory path will be displayed there, and should looke something like:
    • Windows: "C:\Users\Username\AppData\Local\Temp\build[random number].tmp\a_Hello.cpp.hex".
    • GNU/Linux: "/tmp/build[random number].tmp/a_Hello.cpp.hex"
    • Mac : Type open $TMPDIR in your mac's terminal to open the folder that is otherwise not accessible. You can then make a shortcut to your desktop.
  • You can also change the build path in "arduino/lib/preferences.txt" by changing the line #build.path= to build.path=(directory you want).
  • Navigate to this folder and find the .hex file with the name of your program
  • Rename it to a 8:3 format: only capitals, 8 characters max for the name and .HEX extension. For example: CRABATOR.HEX or PONG.HEX

Put it on the micro SD card

Put your .HEX file with a 8:3 name on your micro SD card using any micro SD card reader. You can now select the .HEX file on your Gamebuino to load it on the go, without a computer! Do NOT turn off your Gamebuino while flashing.

Add a logo and description

Error creating thumbnail: Unable to save thumbnail to destination

If you want your game to appear with a logo and description in the loader, you have to create an .INF file and put it along the .HEX file on the SD card.

  • Get the INF encoder from the Download page (requires Java).
  • Put the generated .INF file along with the game's .HEX file on the SD card. They must have the same name, all in capitals, and 8 characters max. For example CRABATOR.HEX (the game binaries) and CRABATOR.INF (the description file).
  • Logo must be 19*18px
  • Slides must be 84*32px, up to 255 slides is allowed.
  • Drag and drop slides to reorganize them
  • The first slide is the one shown while the game is loading
  • Slides can be used to describe the game, tell the story, explain how to play, etc. By putting this information in the INF you can read it before loading the game, everything that's in the .INF don't need to be in the .HEX so it frees some space for your code.

See Also