Kaimana Overview & Instructional Guide
Overview
The Kaimana LED Controller is a powerful new tool for those looking to get the most out of their custom arcade stick or cabinet! Based on the infinitely flexible Arduino, this board can do just about anything you can imagine. Because it uses the extremely simple to learn Arduino programming language, this board opens the gate for anyone to create their own light patterns and shows.
If you're not of the programming mindset, not to worry, in the future there should be community made patterns (that will be compiled into files called Sketches, Sketchbooks, or Libraries (depending on complicity/number of patterns)) that you can easily download and install.
For ease of use with the current industry standard, the Kaimana has the same pin order as the PS360+. Thanks to the fact that the Kaimana has dedicated headers for the LEDs, there is also a simple but revolutionary aspect to its design, it's a direct pass through. Being a passthrough means that you no longer need to double up wires at any of your headers. This means that clean wiring is possible for anyone willing to take the time to rout the harnesses neatly!
Kaimana J
Kaimana Js are a new RGB button LED with an incorporated 2811 chip that the Kaimana can index and control. They can easily be daisy chained with the Kaimana harnesses.
Adapter Board
Most LEDs on the market don't have the indexing capabilities that a 2811 chip can provide. Thankfully Paradise Arcade Shop has you covered. With these new adapter boards you can add a 2811 chip to any RGB LED including Pele Rings and generic RGB LEDs (some soldering may be required).
Installation & Setup
Make sure that you have the following:
§ Kaimana LED Controller Board
§ LEDs (Compatible LEDs Listed below)
§ Kaimana Harness kit
Almost every part about the install process of the Kaimana is fairly straight forward; daisy-chain the headers, always being sure that you are connecting OUT to IN.
However, there is one small part of the process that is both crucial for the board to function and not “in your face” labelled: You have to connect power into one of the headers at the bottom of the board or you can splice 5volts anywhere into your daisy-chain.
Power from board:
Power direct to chain:
Kaimana power header:
List of Compatable LEDs
§ Kaimana Js
§ Pele Rings (adapters needed)
§ Ulia S Flash
§ Standard RGB LEDs
Kaimana Power
The Kaimana controller was designed with flexibility in mind and has two distinct and separate power zones that share a common ground.
§ Zone 1 = Kaiamana - controller/logic/usb power
§ Zone 2 = LED power
When driving a few dozen LEDs, power for the LEDs can be supplied from the USB or the VCC headers along the side of the Kaimana. Simply connect one of the VCC headers to VCC (+5 VDC) on the LED power connector.
Driving a large number of LEDs (several hundred) is possible but will require more power than the Kaimana USB or VCC headers can supply. If an external power supply is required, the secondary LED connector can be used to supply power to the LEDs.
The Kaimana LEDs are connect in a continuous chain starting with the Kaimana board and working outward to the last LED. The LED ID numbering starts with zero (0) for the first LED directly attached to the Kaimana board, one (1) for the second LED, two (2) for the third and so on until you reach the end of the chain.
The figure below shows the default LED configuration that shipped with the initial Kaimana release. You can modify the order of the LEDs in the chain but will need to change the LED name to ID# mappings listed in the “Driving the Kaimana LEDs” section below.
Basic Guide to Arduino Programming
I'm not a great teacher, never have been, never will be. So, rather than making some sour attempt to “teach” you how to program an arduino, I'm going to take you on a guided tour of the portions of the internet I used when I taught myself how to program for arduino. We won't make any dives into advanced robotics here but if you explore the sites that I reference here I'm certain you will find what you need for just about any possible function. So, with no more delay, let's get started.
Note: The Kaimana is based on the Arduino Leonardo. Remember to set your Arduino programming software to code for Leonardo before you start, or you may get false errors when you try to compile and upload your code. You can set this by going to Tools → Board → Arduino Leonardo
Links
The first place I started was where many might expect; the Arduino Wiki. A Wiki is a nice stepping stone that most people are acquainted with, it should give you a basic idea of what your dealing with at the very least on a hardware level.
http://en.wikipedia.org/wiki/Arduino
The Arduino website is very well laid out and has pretty much every piece of information we could want, but some (including myself) have found that it's link order and over-arching map difficult to navigate. So I'm going to go in order, from most to least important, and then give you links to reference pages that you should always keep on hand.
1. http://arduino.cc/en/Guide/Introduction -This is where to start. It has a great explanation of what arduino is and why you should use it.
2. http://arduino.cc/en/Guide/HomePage -This is where you can actually download the client and find the next few links.
3. http://arduino.cc/en/Guide/Environment -Here you can find an in-depth explanation of Sketches, Sketchbooks, and Libraries. This is crucial for programming!
4. http://arduino.cc/en/Guide/Libraries -This will take you more in-depth on the Library installation process.
5. http://arduino.cc/en/Reference/Changes -It is important to stay current with changes in the coding language, Here is the changelog.
6. Next up are pages that you should keep on hand while your programming. Bookmark these!
a. http://arduino.cc/en/Reference/HomePage -Contains a “dictionary” of terms used within the coding language.
b. http://arduino.cc/en/Tutorial/HomePage -Contains great examples of other people's work and uses color to show the structure.
c. http://arduino.cc/en/Tutorial/Foundations -This is kind of an ultimate guide to the terminology.
Books
Now, the web is a wonderful source for all kinds of knowledge, but sometimes a book is just the best way to go about learning something new. Books by great instructors or important persons in the industry are sometimes the most credible route to the most efficient ways of tackling coding issues. Here are links to some of the books I found most helpful during my projects.
2. Programming Arduino Getting Started with Sketches
3. Beginning Arduino Programming
Videos
Nowadays there are many ways of learning something new, Video is one of the most popular in our current society. It's even becoming prominent in schools, especially with the advent of programs like Lynda.com. Arduino is no different. Here I'll be listing videos and/or channels you should check out, if a single person is the creator of a plethora of good and relevant content I'll give them a shout out.
Be sure to Like/Comment/Subscribe to them if you like what you see.
§ Tutorials for Arduino by Jeremy Blum - Jeremy Blum has one of the most extensive and informative Arduino tutorial series on the web. He deserves all kinds of respect from any community that decides to step into the realm of arduino, this man is a master. If you are serious about learning to code for Aduino you owe it to yourself to watch this series!HIGHLY RECOMMENDED
§ Arduino Tutorials by HumanHardDrive - HumanHardDrive's Arduino tutorials are nice although a little less focused on the programming side of things.
Arduino Leonardo / Kaimana Digital Pin Mapping
This is the nitty-gritty technical info that most everyone familiar with the Arduino programming environment will eventually want when coding some of the more advanced features such as animations.
|
Kaimana |
Arduino Pin |
Arduino Port |
Direction |
|
UP |
18 |
F7 |
INPUT |
|
DOWN |
11 |
B7 |
INPUT |
|
LEFT |
19 |
F6 |
INPUT |
|
RIGHT |
20 |
F5 |
INPUT |
|
START |
10 |
B6 |
INPUT |
|
SELECT / BACK |
9 |
B5 |
INPUT |
|
HOME / GUIDE |
8 |
B4 |
INPUT |
|
1P |
3 |
D0 |
INPUT |
|
2P |
2 |
D1 |
INPUT |
|
3P |
0 |
D2 |
INPUT |
|
4P |
1 |
D3 |
INPUT |
|
1K |
4 |
D4 |
INPUT |
|
2K |
21 |
F4 |
INPUT |
|
3K |
12 |
D6 |
INPUT |
|
4K |
6 |
D7 |
INPUT |
|
LED DATA OUT |
23 |
F0 |
OUTPUT |
Reading Kaimana Switch Input Pins
The state of each Kaimana switch can be read from the Arduino programming environment with a digitalRead(ARDUINO_PIN_NUMBER) command. The digtalRead command returns either a HIGH or LOW based on the input pin state. Because of the way both the XBOX and PS3 work, the joystick and button pins are held HIGH when idle and go LOW when active. While this feels reversed, it is correct.
For example, to test if the joystick up direction is active, we need to read the Arduino pin 18 and test for a LOW (active) state.
if( digitalRead( 18 ) == LOW )
your_code_call_joystick_up_active(); // fictional function you need to write
If you are working with the Kaimana example code provide by Paradise Arcade Shop, there are pre-defined names for each of the Arduino pins to make reading the coding easier. The following code is identical to the previous example for testing the joystick up switch.
if( digitalRead( PIN_UP ) == LOW )
your_code_call_joystick_up_active(); // fictional function you need to write
And the streamlined version of the same code which you will see used in most of the example code.
if( !digitalRead( PIN_UP ) )
your_code_call_joystick_up_active(); // fictional function you need to write
As of this writing, the demo code shipping with the Kaimana provides the constant definitions listed below. The names and values can be modified to suit your needs. Since the Kaimana has 15 switch inputs which logically translated into 12 LED outputs, we decided to keep the demo as simple and logical as possible to be used as an educational tool.
Note that PIN_HOME and PIN_GUIDE have the same value as do PIN_SELECT and PIN_BACK. This was done to provide a familiar naming convention so you can use PIN_HOME or PIN_GUIDE in your code and achieve the same results. Some of the early adopters preferred the xbox 360 naming convention while others requested the PS3 names so we decided to included both.
// Map switch function names Arduino digital pin numbers
// specific to ParadiseArcadeShop.com Kaimana board (PS360+LED)
// change or expand as needed
#define PIN_DOWN 11
#define PIN_UP 18
#define PIN_LEFT 19
#define PIN_RIGHT 20
#define PIN_HOME 8
#define PIN_GUIDE 8
#define PIN_SELECT 9
#define PIN_BACK 9
#define PIN_START 10
#define PIN_P1 3
#define PIN_P2 2
#define PIN_P3 0
#define PIN_P4 1
#define PIN_K1 4
#define PIN_K2 21
#define PIN_K3 12
#define PIN_K4 6
Driving the Kaimana LEDs
The Kaimana core low level routines are supplied in the Kaimana class library (kaimana.cpp and kaimana.h). To access these functions you will need to include the kaimana.h file at the top of your arduino project code as shown in the example file.
// include the Kaimana class library
#include "kaimana.h"
Next you need to instantiate the class library so you have access to the Kaimana class variables and functions. Classes are nothing more than convenient wrappers to organize variables, functions and even data.
// ParadiseArcadeShop.com Kaimana features initialzied when Kaimana class instantiated
Kaimana kaimana;
If you are working with the Kaimana example code provide by Paradise Arcade Shop, there are a number of functions provided facilitate driving the LEDs. The three basic functions for managing LED are the ability to change the color of a single LED, change the color of all LEDs and to send the latest color changes to the physical LEDs.
kaimana.setLED( LED_number, RED_value, GREEN_value, BLUE_value )
kaimana.setALL( RED_value, GREEN_value, BLUE_value )
kaimana.updateALL()
Note that the setALL function is instantaneous and automatically updates the LED strip. The setLED function queues up the LED color changes until the updateALL function is called.
To turn off all of the LEDs attached to the Kaimana, we set the color to BLACK (RED=0, GREEN=0, BLUE=0). This can be done different ways but the two examples below achieve identical results.
// this command
kaimana.setALL( 0, 0, 0 );
// is identical to this command
kaimana.setALL( BLACK );
To set all of the LEDs to bright RED we can use the following kaimana.setALL code.
// this command
kaimana.setALL( 255, 0, 0 );
// is identical to this command
kaimana.setALL( RED );
Let's say you want to turn off all the LEDs then set the first LED to RED. For that we need to understand that the Kaimana LED index starts with 0 not 1. This is how Arduino c arrays work so we stayed with the Arduino programming standard for simplicity. We have also defined a human readable constant of LED_JOY = 0 to make the code easier to read and clearly let everyone know which LED is being set. If the joystick LED is the first LED connected to the Kaimana board then you are all set. You can also change the constants if you decide to wire your board differently.
// turn off all LEDs (set color to BLACK)
kaimana.setALL( BLACK );
// set first LED (#0) to RED
kaimana.setLED( 0, 255, 0, 0 );
// is identical to this command
kaimana.setLED( LED_JOY, 255, 0, 0 );
// is identical to this command
kaimana.setLED( LED_JOY, RED );
// send the new color values to the LEDs
kaimana.updateALL();
As of this writing, the demo code shipping with the Kaimana provides the constant definitions listed below. The names and values can be modified to suit your needs and the number of LEDs expanded if desired. Since the Kaimana has 15 switch inputs which logically translated into 12 LED outputs, we decided to keep the demo as simple and logical as possible to be used as an educational tool.
Note that LED_HOME and LED_GUIDE have the same value as do LED_SELECT and LED_BACK. This was done to provide a familiar naming convention so you can use LED_HOME or LED_GUIDE in your code and achieve the same results. Some of the early adopters preferred the xbox 360 naming convention while others requested the PS3 names so we decided to included both.
// Map function names to LED index numbers
// specific to ParadiseArcadeShop.com Kaimana board (PS360+LED)
// change or expand as needed
#define LED_JOY 0
#define LED_HOME 1
#define LED_GUIDE 1
#define LED_SELECT 2
#define LED_BACK 2
#define LED_START 3
#define LED_P1 4
#define LED_P2 5
#define LED_P3 6
#define LED_P4 7
#define LED_K1 8
#define LED_K2 9
#define LED_K3 10
#define LED_K4 11
Author's notes
If you would like to get involved in the Kaimana discussion, have suggestions, looking for help or just want to read more, check out the SRK forum thread dedicated to the Paradise Arcade Shop Kaimana product.