back
Teensy Saber OS (beta)
Got Pike?
DIY Teensy based lightsaber


BETA VERSION WARNING
Note that the software is still in beta, not all features are implemented, and not everything is well tested. However, the software is functional and works well for me.

What you will need:

Download version 1.43 here

ChangeLog (since 1.40)
  • Looped swing sounds supported.

Features

  • 100% open-source, you may add any feature you like.
  • Speedy 32-bit processor makes advanced features like sound filters, synthesizing and mp3 playback possible.
  • 12-bit digital-to-analog output
  • Default sample rate is 44kHz
  • 22kHz and 11kHz samples are supported and upsampled to 44kHz automatically.
  • Gapless playback, with 2.5ms cross-fade when you interrupt one sample to go to another.
  • Polyphonic playback, currently configured for up to 5 simultaneous samples.
  • Support for PL9823 or neopixel strings.
  • Support for arbitrary 1/2/3/4-color stars/strings.
  • Supports segmented string blades.
  • Power-level indicator with neopixel blade.

Features which are not yet implemented, but should be easy to add

  • Accent LEDs.
  • A way to upload files to the SD card through the micro-usb cable.
  • Multiple blades.
If you want any of these features, contact me on the fx-sabers forum and I'll see what I can do.

Install
There are plenty of instructions on the Aruduino and PJRC web sites for how to install the Arduino and Teensyduino software, they both also have forums in case you need help. Once you have them installed, you should be able to open up lightsaber.ino, select the Teensy 3.2 as the target board, compile and upload to the board.

Configuration
While you can obviously change *anything* in the source, the parts you may need to change depending on how you wired your electronics is maked with a CONFIGURABLE comment, so go find those and modify them to your hearts content.

Button configuration
By default, TeensySaber is configured to use a touch button for power, while the other buttons use regular momentary switches. There is currently no support for latching switches. If you want to use a momentary switch for the power button, you'll need to change two things.

  1. Find the line that says TouchButton power_; and replace it with Button power_;.
  2. Find the line that says power_(powerButtonPin, 1700, "pow"); and replace it with power_(powerButtonPin, "pow");. (The 1700 is the sensetivity of the touch button, at some point I might calculate the sensetivity automatically, and then this step won't be required anymore.)
Note that you can do the opposite of these two steps to the other buttons if you want to make them into touch buttons.

LED configuration
The teensysaber already contains definitions for some popular Cree LEDs, so most of the time, all you need to do is to change the R = to match the resistor you use. If you use a different LED, make a copy of onf of the LED structs and modify it.

struct MyRedLED {
  static constexpr float MaxAmps = 1.0;
  static constexpr float MaxVolts = 3.15;
  static constexpr float P2Amps = 0.7;
  static constexpr float P2Volts = 3.05;
  static constexpr float R = 0.55;

  // LED color
  static const int Red = 255;
  static const int Green = 0;
  static const int Blue = 0;
};
MaxAmps & MaxVolts is the amps and volts when the LED is fully on. It's best to get these values from the data sheet if possible. If not, you'll have to guess the MaxAmps, and measure at what voltage you get that. The P2Amps and P2Volts are similar, but at some other point, for instance when the LED is half-on. If the data sheet doesn't provide this, it is fine to just measure it. R is the value of the resistor you used, zero if there is no resistor.

Color configuration
Most of the time, TeensySaber simply uses RGB colors to run everything, however, if you're using an LED star, things can get a bit more complicated. For instance if you have a Blue-Blue-White LED star, you have two choices for how to configure the driver class. The first choice is something like: SimpleBladePtr<CreeXPE2Blue, CreeXPE2Blue, CreeXPE2White, NoLED>(). This means that when the Style classes tells the blade to be blue, the channel one and two turns on, and when the style class say to make it white, all three channels turn on. This is usually what you want to make the blade flash on impact. With this setup, the style setup becomes simple as well, you just do something like: StyleNormalPtr<BLUE, WHITE, 300, 800>(). However, there is one drawback; if you want to actually use the white LED by itself, there no way to do it. The only way to activate the white LED is for the Style to specify a white color, and that will also activate the blue LEDs.

We can get greater control over the color combinations by re-defining how colors are defined. We'll need to make copies of the CreeXPE2Blue and CreeXPE2White classes, like so:

struct MYCreeXPE2White {
  static constexpr float MaxAmps = 1.0;
  static constexpr float MaxVolts = 3.15;
  static constexpr float P2Amps = 0.7;
  static constexpr float P2Volts = 3.05;
  static constexpr float R = 0.55;

  // LED color
  static const int Red = 0;
  static const int Green = 0;
  static const int Blue = 255;
};

struct MYCreeXPE2Blue {
  static constexpr float MaxAmps = 1.0;
  static constexpr float MaxVolts = 3.4;
  static constexpr float P2Amps = 0.35;
  static constexpr float P2Volts = 3.1;
  static constexpr float R = 0.24;
  static const int Red = 255;
  static const int Green = 255;
  static const int Blue = 0;
};

And we'll add some new defines: #define BBW_BLUE 255,255,0 and #define BBW_WHITE 0,0,255. Now we can set up the blade like so: SimpleBladePtr<MyCreeXPE2Blue, MyCreeXPE2Blue, MyCreeXPE2White, NoLED>(). And the style configuration becomes StyleNormalPtr<BBW_BLUE, BBW_WHITE>(). This makes the flash pure white, and the blue LEDs are turned off during the flash. If we want to turn on both, we can do that by specifying 255,255,255.

Sound Fonts
Once you have the firmware installed, you'll need at least one sound font. Sound fonts are stored on the SD card, just create a subdirectory and put the files from the font in there, and it should work. Most fonts are monophonic, meaning that only one sound is played at a time, but some are polyphonic, meaning that sound effects are played over the basic humm sound of the saber. The teensy saber os supports both types and should be able to figure out what kind it is based on the file names. Here are a few places where you can obtain sound fonts:

Sound Effect File Names
A sound font is made up of many sound files, the filename of these files should look something like this:

font1/clash001.wav
The file name is made up of four parts:
  1. The directory - This can be anything you like. All the files belonging to the same font should be in the same directory though. You can put fonts in sub-directories if you like, so it could be something like: fonts/dark/1/hum.wav if you like. The first entry in the preset[] array specifies the directory.
  2. The name - One of a set of pre-defined names specified below.
  3. The number - When playing a sound, TeensySaber will generally pick one of them randomly. The numbers can either be on the form 1,2,3,4,5,6,7,8,9,10,11, etc. or 01, 02, 03, etc. or 001, 002, 003, etc. The number sequence must be consistent and without any gaps. It's also possible to omit the number completely. For looping sounds, TeensySaber will randomly pick one of the numbered files each time it starts over, so it's possible to create a more interesting hum by having "hum.wav", "hum1.waw", "hum2.wav" etc. Note that since we're using an ancient file system, the length of the name and number must not total more than 8 characters. (So you can only have 11 poweron sounds: poweron.wav, poweron0.wav, poweron1.wav....poweron9.wav)
  4. The extension - The extension should be .wav. 11, 22 and 44khz mono/stero wav files are supported.

Sound Effect Names
The name part of the filename needs to be one that TeensySaber can recognize. Sound fonts can either be monophonic (Plecter) or polyphonic (Naigon Electronics) style. In monophonic mode, the following names are recognized:

  • boot - Played when TeensySaber boots up.
  • swing - Played when you move the saber around.
  • hum - Played when you don't move the saber around. (looped)
  • poweron - Played when you turn the saber on.
  • poweroff / pwroff - Played when you turn the saber off.
  • clash - Played when you hit something with the saber.
  • force - Force use sound.
  • stab - Played when you make a stabbing motion. (Not yet implemented)
  • blaster - Played when you press the AUX button.
  • lockup - Lockup (not yet implemented)
  • poweronf - Force power on (not yet implemented)
  • font - Played when you switch to this font / preset.
Note that in monophinic mode, the end of all sounds (except poweroff) smoothly join up with the beginning of the "hum" sound(s).

In polyphonic mode, the following names are recognized:

  • boot - Played when TeensySaber boots up.
  • swng - Played when you move the saber around.
  • hum - Played when you don't move the saber around. (looped)
  • out - Played when you turn the saber on.
  • in - Played when you turn the saber off.
  • clsh - Played when you hit something with the saber.
  • force - Force use sound.
  • stab - Played when you make a stabbing motion. (Not yet implemented)
  • blst - Played when you press the AUX button.
  • lock - Lockup (not yet implemented)
  • font - Played when you switch to this font / preset.
TeensySaber will automatically decide if a directory contains a monophonic or polyphonic font based on the filenames.

In addition, if the sounds "swingl" and "swingh" are present, they are assumed to be looped hum-style sounds. TeensySaber will blend the hum/swingl/swingh sounds to create swing effects instead of using the swing/swng sounds.

Serial Monitor Commands
You can use the serial monitor to debug and control the software once uploaded, here is an incomplete list of commands:

  • help - prints a list of known commands
  • on - turns the saber on
  • off - turns the saber off
  • blade on - turns the blade on (but leaves the sound off)
  • blade off - turns the blade off
  • clash - trigger a clash effect
  • dir [directory] - list files on sd card
  • cd [directory] - change directory, and sound font
  • play [file] - play wav file
Note that there is a drop-down at the bottom of the serial monitor that defaults to "No Line Feed", you must change it to "Newline" to use the serial monitor with TeensySaber.

Download Older versions

  • 1.8 - pre-alpha version
  • 1.10 - alpha version
  • 1.11 - beta version
  • 1.14 - first recommended version
  • 1.18 - preliminary teensy 3.5/3.6 and TeensySaber V2 support
  • 1.19 - Fixed BUILTIN_SDCARD
  • 1.20 - Fixed hang when reading directories ending in /
  • 1.40 - new LED configuration system, PWM over volt protection, audio bugfixes, improved audio buffering, better help system, multiple touch buttons, code cleanup

Troubleshooting
If you're having problems, check out the troubleshooting page.

Problems? Questions? Suggestions? Check out the fx-sabers online forum.
This page has been accessed 1,081 times since July 25th, 2016.
Last modified: March 13th, 2017 - Design by Monica & Fredrik Hübinette