search

leethomason / OpenSaber

Source code, circuits, and documentation for making an Arduino and compatible based light and glowy saber.
40 stars 8 forks source link

readme

Welcome to Open Saber

The goal of open saber is provide source code, circuit diagrams, and documentation for making an Arduino (and compatible) based lightsaber. The focus is on the internals of the saber, not how to build the case.

Why? For the joy of the problem, working together, and learning / playing with Arduinos. There are certainly commercial solutions to saber electronics, but if you want to build and contribute to the code and internals, this site is for you!

The information and documentation assume a basic knowledge of Arduinos, electronics, soldering, etc.

In 2017, the design switch from through hole components, which have wires and can be fairly easily hand soldered, to SMD components, which need to be flow soldered in an oven. The current code uses only the SMD approach. If you are interested in the through hole approach, check out the source at FIXME

Image of Saber

The Open Saber site / repo is 3 things:

An Open Saber electronics in action here: https://youtu.be/9_-Rfe4UBJM.

Features:

Status & Direction

There are over 5 working sabers on the OpenSaber design with cases by SaberZ, UltraSabers, TCSS v1, and SaberForge ASP.

The version number - as much as it is consistent - references the PCB board. The PCB board is called a "shield" because it sits on top of a Teensy Microcontroller.

I use the largest possible SMD components to make it as straightforward as possible for a human to solder. They are still small.

Generally speaking the shields sit on a Teensy 3.5. You can also use a Teensy 3.2, but you need to connect an SD card on the SPI interface. (The 3.2 does not have an integrated SD card.)

Note that many commits to the github repo are parts for a 3D printer. While you are welcome to use them, the focus of this site is the electronics, which can be re-used from saber to saber. The physical parts are unique to each saber (unless you use a standard case, of course.)

Image of Saber

Alternate Approaches

Resources

I am not affiliated with any of these, but have found them all useful.

General

How To

Saber bodies

LEDs

Electronics

Architecture

An overview of the parts of a saber, with specific examples of the Gecko.

Technically speaking, to organize you electrical thoughts, a saber is a very fancy flashlight.

In roughly front to back order, an saber is:

  1. A blade holder. (1" is standard.)
  2. A lens to focus the LED. The lens is bought to match the LED, and narrower is usually better.
  3. 3 LEDs in the 1-Watt each range. Red, green, blue, and sometimes white or another color. I like both the Luxeon and Cree XPE-2. I haven't experimented with the 12W LEDs yet; electrically most of the designs should handle it, but the power from the battery and the cooling are potential issues.
  4. A heat sink for cooling the LED. Often part of the saber body. TCSS provides them as well. LEDs are kept to 350ma - 400ma each (although you can change this.) Many LED's, if cooled correctly, can take considerably more power. Conversly, many sabers with poor heat sinking fail over time as their LEDs burn out.
  5. Power and Auxillary switches (momentary on, typically 12mm). The code supports both a one button version and a two button version. Both versions support the same features except "clash sound" which is only supported in the 2 button version. If the switches have LED rings, the microcontroller will use them for power / volume display.
  6. Electronics. Please see the full discussion below.
  7. Power port. Typically 2.1 mm. If plugged into a Li-Ion charger, charges the battery (and disconnects the microcontroller). If a kill key is inserted, turns off the saber.
  8. SD Card. A simple SD card breakout board or integrated card. This is where the sound fonts are stored. Note that the saber code WILL NOT work without sound fonts stored and named properly on the MicroSD card. Also, if using the Teensy 3.5, the SD card is integrated.
  9. 3.7v Li-Ion battery. TCSS and Adafruit both sell good, small, long lasting batteries. Need something rated 2000mAh or better. Amazon as well carries protected Li-Ion batteries. (The Panasonic NCR18650B 18650 has been recommended.)
  10. Speaker. TCSS and Adafruit carry them, as well as Mouser and Digikey. (I've had a lot of inexpensive speakers arrived damaged from China, so I do recommend a reputable supplier.)

Directory Organization

Wiring

FIXME new wiring diagram

LEDs

LEDs are used in a bunch of places. Specific concerns are discussed below, but for all the LEDs it's good to have a handly calculator. The Vf comes from the LED data sheet. The Vsource depends on which circuit it is connected to.

A LED calculator: http://led.linear1.org/1led.wiz

This calculator will select the next higher standard resistor, which is almost always what you want. However, if you want to calculate the exact resistance:

R (ohms) = (Vs - Vf) / amps_through_led

Specific LED usage:

Power Bus

The saber uses a common ground. There are 4 positive power voltages. Please be aware of the power supply. Shorts between the supplies can cause big issues. It's very important to not "cross" the power supplies or use the wrong one.

Power Port

Convention, and the current design, uses a 2.1mm recharge jack. Wiring of the jack is such that:

  1. the battery charges when the charger is plugged in
  2. the circuit is dead when there is a non-conductive kill key plugged in
  3. the circuit is live when nothing is plugged in, which is also indicated by the ring LED if you use that type of momentary switch.

This is useful, and convention for almost all saber designs, but a little weird. For it to work (safely) for case #1, the grounded sleeve of the recharge port should be isolated from "true ground" and the case of the saber. You need to be careful with a metal port, or use an insulated plastic one.

3V or 7V

Sabers run off 4 AAA, 3.7 Li-Ion, or 7.4 Li-Ion. OpenSaber is designed around a 3.7 Li-Ion.

Why?

3.7v

Note that the actual battery voltage varies significantly, and the control circuit accounts for that.

Electronics

The electronics are the heart of the OpenSaber project. The files are ExpressPCB files. I regret the proprietary solution, but I've been happy thusfar with the service.

The shield - which is the PCB that sits on top of the Teensy - collects together 1) an audio amplifier, 2) a DotStar LED controller, 3) an accelerometer, and 4) and emitter LED power onto one board. It also provides an SPI inteface connection for an external SD card, display, or similar.

Switches

The code assumes 1 or 2 switches.

In a 2 switch configuration, you may also (when the blade is on) hold auxillary and then tap the main switch to cycle through the blade color / sound palettes.

In a 1 switch configuration, a tap mode switches between "blade", "palette", and "volume". Long press either turns the blade on/off, or selects the palette or volume.

Audio

Audio playback is integrated into the main micro controller. It takes 44.1kHz in; you will need to convert files to 44.1k. They are typically not 44.1kHz when provided, so you will need to convert.

You can have up to 10 sound "fonts" or sound banks. Each font needs to be in its own sub-directory, which will be the name of the font.

All the names can be postfixed with a number for random variation: SWING or SWING01 for example. Note that the card / code is limited to 8.3 filenames. You can't mix names in a group; using both BLDON and POWERON in the same sound font will confuse the sound output.

Code

The code is really the heart of this project. The code is set up to compile in the Arduino IDE, using the Teensyduino extension.

First you will need to set up libraries. Then you need to configure you particular saber in "pins.h".

Libraries

I feel guilty about every forked library; but it's hard to work around API issues. Theser are minor forks, at least.

Accelerometer

The current design uses the (really great) LIS3DH. https://github.com/leethomason/Adafruit_LIS3DH

OLED

The OLED display is required to compile, although it isn't supported as part of OpenSaber yet. (I use it in a personal saber.)

https://github.com/leethomason/OLED_SSD1306

Config Files

'pins.h'

'pins.h' contains the wiring pinout, documentation, and features switches. The tricky #define is the SERIAL_DEBUG macro. If on, you can connect the USB header and debug the saber. However, without a USB connection, the saber won't work if SERIAL_DEBUG = 1. The serial port won't be found, the timeouts kick in, and the saber essentially "locks up". It's a great to be able to debug, but remember to SERIAL_DEBUG=0 and upload that sketch when you are done.

Pins contains a bunch of other macros, which you can disable when you build the saber, and turn on one by one.

'pins.h' also contains the description of the LED: forward voltage, resistor values, etc. You need to set this for your particular build.

Note that there is an equation for UVOLT_MULT which controls the volt meter. There's some variability; once the saber is assembled, I suggest adjusting this value by checking computed vs. measured values. (Type 'vbat' on the command line to get the current computed value.)

"Constant Current" and tuning the voltmeter.

The OpenSaber code will maintain an average of 350mA current (or whatever you specify) across the LED. This block of code in pins.h is important for tuning:

  static const int32_t UVOLT_MULT = 6680;
  #define ID_STR "Gecko (Sentris Body) RGB Luxeon"

  static const int32_t RED_VF   = 2900;   // milli-volts
  static const int32_t RED_I    = 350;    // milli-amps
  static const int32_t RED_R    = 2400;   // milli-ohms

VF: forward voltage, from the LED spec. I: milli-amps of power R: the resistor value you used

And finally the UVOLT_MULT. It's a little tedious to calculate, and doesn't turn out to be useful to do so. Once your saber is up and running, wait until it hits the 3.7 volt range. Measure the power with a voltmeter. Run vbat on the saber command line to get the measured value. Adjust UVOLT_MULT, and recompile.

UVOLT_MULT' = UVOLT_MULT * V_measured / vbat

And then re-check the vbat just to be sure. It should be close, but doesn't need to be exact.

Command line

If you connect via USB, you can open the COM port to the saber and issue commands. Do this by opening the Serial Monitor and entering comminds in the terminal that appears. This works irrespective of SERIAL_DEBUG.

The saber has 8 palettes. The palette is a combination of:

Future Direction

In practice I've found that there are two drivers to the design:

Image of Saber