Table of Contents
Modifying the Sketch
Once you open the sketch in the Arduino IDE you will see several tabs along the top. There are two tabs we will be interested in, called “AA_LightSetup” and “AA_UserConfig.h”
AA_LightSetup Tab
Note: Nick Segers has made an Excel file that will automate the generation of this entire section. Download it from the list of files on the Downloads page
This tab is where you specify the Setting for each light for each State as well as where you can create multiple Schemes. Basically each scheme consists of a table. Each table has 8 rows, one for each of the 8 lights. Each column in the table represents one of the light States. The values in the table are whatever Setting that light will be in for that State. The Settings must be typed in all upper-case, refer to the list below for acceptable values.
// SCHEME ONE - EXAMPLE PROVIDED // Pos 1 Pos 2 Pos 3 Pos 4 Pos 5 Forward Reverse Stop StopDelay Brake Right Turn Left Turn No Turn Accelerating Decelerating // ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- { OFF, OFF, XENON, XENON, XENON, NA, NA, NA, NA, NA, NA, NA, NA, FASTBLINK, NA }, // Light 1 -- Headlight One - XENON on when Channel 3 is in the middle-to-far position - FASTBLINK on overtaking { FADEOFF, FADEOFF, ON, ON, ON, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA }, // Light 2 -- Headlight Two - ON when Channel 3 is in the middle-to-far position, fadeoff otherwise { OFF, OFF, DIM, DIM, DIM, NA, NA, NA, NA, ON, NA, NA, NA, NA, NA }, // Light 3 -- Brake Light - ON when Braking, otherwise DIM if Channel 3 is in the middle-to-far positions { OFF, OFF, DIM, DIM, DIM, NA, NA, NA, NA, NA, SOFTBLINK, NA, NA, NA, NA }, // Light 4 -- Right Turn Lights - SOFTBLINK when turning Right, otherwise DIM if Channel 3 is in middle-to-far positions { OFF, OFF, DIM, DIM, DIM, NA, NA, NA, NA, NA, NA, SOFTBLINK, NA, NA, NA }, // Light 5 -- Left Turn Lights - SOFTBLINK when turning Left, otherwise DIM if Channel 3 is in middle-to-far positions { OFF, OFF, OFF, OFF, OFF, NA, ON, NA, NA, NA, NA, NA, NA, NA, NA }, // Light 6 -- Reverse Lights - only on when moving in Reverse { OFF, OFF, OFF, OFF, OFF, NA, NA, NA, NA, NA, NA, NA, NA, NA, BACKFIRE }, // Light 7 -- Muffler Light - special backfire effect when decelerating { OFF, OFF, OFF, OFF, OFF, NA, BLINK, NA, NA, NA, NA, NA, NA, NA, NA } // Light 8 -- Backup hazards - blinks when car is in reverse.
These are the list of Settings you can specify:
- ON
- OFF
- FADEON (turns on slowly)
- FADEOFF (turns off slowly)
- BLINK
- BLINK_ALT (same as BLINK but alternating)
- FASTBLINK
- FASTBLINK_ALT (same as FASTBLINK but alternating)
- SOFTBLINK (emulates old style incandescent turn signal lights)
- DIM
- XENON (a special turn-on effect)
- BACKFIRE (blinks lights randomly for a short period of time, use this under the Decelerating state for tailpipe/muffler LEDs)
- NA (Use this when you don't want a State to do anything)
Don't worry about the PROGMEM uint8_t stuff or anything that looks confusing. Just change the values (OFF, ON, etc…) remembering to spell things correctly and keeping a comma between each one.
AA_User_Config.h Tab
This file has all the adjustments the user can make to the operation of the device. Each adjustment is described at length with comments in the code, but they are discussed here as well.
Each setting begins with the “#define” keyword followed by the adjustment name. These should not be changed. After the adjustment name comes the value, which is usually a number or true or false, and these are what you will change. When entering true or false, be sure to type them in lower case.
Number of Schemes
#define NumSchemes 2
This number must match the number of Schemes you have defined in the AA_LightSetup tab! You can have as many Schemes as you want, up to the code limit (it would be a lot). The default number is 2.
Speed Controller
#define DoubleTapReverse true
Most ESCs require you to apply reverse twice before the car actually goes into reverse. If you are using this type of speed controller, set this value to true. Most touring cars operate like this. But if you can shift directly into reverse from forward, set this to false - this is typical of crawlers.
Radio Adjustments
Channel Deadband
#define ThrottleDeadband 10 #define TurnDeadband 20
Because the receiver signal will tend to drift even when your radio controls are resting at center, you may find your turn signals or other lights turning on randomly. To prevent this from happening you can adjust the deadband, and if that is insufficient, you can enabled channel smoothing (discussed below). Start with deadband first, it reduces the sensitivity around the channel center point. The channel values (as used in this program) range from 0 (center) to 100 (full travel). If you set the deadband to 10, that means any command of 10 or less will be ignored. This will reduce sensitivity, but since we are only controlling lights here and not the actual vehicle, that's fine. Experiment with the values, but keep them as low as practical.
If that doesn't work, try channel smoothing below. Another thing is to try running through Radio Setup again, to make sure OSL really does know your radio's actual center points.
Channel Smoothing
#define smoothingStrength 1 // Number from 0-4, the higher the number the greater the smoothing. Use minimum acceptable value. #define SmoothThrottle false #define SmoothSteering false #define SmoothChannel3 false
Unlike deadband which ignores minor RC changes around the center point, smoothing will average the incoming signals. This will eliminate random glitching, but comes once again at the expense of decreased sensitivity.
State Adjustments
Stop Delay
#define LongStopTime_mS 30000L
The Stop Delay state only occurs when the vehicle has been stopped for some length of time, which is set here. Recall that 1000 mS = 1 second (default value is 30 seconds) (for large define numbers, we put an “L” after the number)
Brake Lights at Low Throttle
#define BrakeAtThrottlePctBelow 0
Background: Normally the Brake state can only occur if DoubleTapReverse = true and you hit reverse for the first time. This doesn't put you into reverse, instead it turns on the brake lights. Only the second time you command reverse will the reverse state actually occur. If DoubleTapReverse = false, there is no way for the brake state to ever occur, because you can instantly transition from forward to reverse and vice versa. Of course you also have the option of setting your brake lights to ON in the Stop state, but then they are always on when stopped, which you may or may not want.
What this setting does: here you can set a percent and whenever the throttle command is above zero but less than or equal to that percent, the Brake state will occur. This allows your brake lights to come on when you slow down, but you are still able to have them turn off when stopped. Set this value to 0 (zero) to disable the low throttle brake lights effect.
Turn Signals
#define BlinkTurnOnlyAtStop true
If you only want your turn signal blinkers to come on when the car is Stopped, set this to true. Turn signals are cool, but they look silly when they start blinking every time you turn the steering wheel while driving. For that reason, you will probably want to keep this “true.”
NOTE: This only applies to a BLINK or SOFTBLINK setting in the “RightTurn” or “LeftTurn” states. Any setting other than BLINK or SOFTBLINK in the “RightTurn” or “LeftTurn” column will NOT be affected.
#define AllTurnSettingsMatch false
Set to true to restrict all other left or right turn settings (not just BLINK and SOFTBLINK) to the same conditions imposed by BlinkTurnOnlyAtStop.
#define TurnSignalDelay_mS 3000
If BlinkTurnOnlyAtStop = true, this setting further refines when the turn signals can come on. Instead of coming on right when the car reaches a stop, you can set a delay in milliseconds (1000 mS = 1 second) before they will be enabled. This way, if you come to a stop while the wheels are turned the turn signals will not come on instantly, which looks very strange. Instead there will be a delay of TurnSignalDelay_mS milliseconds after which you can hold the wheels over and the turn signals will then come on. Once again we are trying to prevent the unrealistic engagement of turn signals, but rather have them only engaged when you specifically want to for display purposes.
#define TurnFromStartContinue_mS 1000
If BlinkTurnOnlyAtStop = true, this setting determines the length of time the turn signal will continue to blink when you begin moving from a stop with the wheels turned. In a real car, the blinker remains on through the turn but then is cancelled after the steering wheel returns to center. That is the effect we are trying to mimic, but we don't do it by checking the steering wheel, we simply set a length of time for the turn signal to continue blinking. If you don't want this effect to happen, set this to 0 (zero).
Acceleration and Deceleration
#define AccelPct 35
How much does the throttle have to increase (1-100 pct) to be considered a sharp acceleration. This will trigger the OvertakeTime timer set below, during which your lights will do whatever setting you put in the Accelerating column (BLINK or FASTBLINK makes sense, like they do in 24hr Le Mans when overtaking)
#define OvertakeTime 500
How long should the overtake event last in ms (1000ms = 1 second)
#define DecelPct 20
How much does the throttle need to decrease (1-100 pct) to be considered a sharp deceleration. This will trigger the Backfire effect for any light in the Decelerating column with the setting of BACKFIRE. You can put other settings in the Decelerating column besides Backfire, and they will work, but they will only be enabled for the same length of time as the backfire event.
#define BF_Time_Short 200 #define BF_Time_Long 600
How long in milliseconds (1000 ms = 1 second) on average should a backfire event last. It will actually be a random length of time spanning from BF_Time_Short to BF_Time_Long.
#define BFF_Short 30 #define BFF_Long 100
The two defines above determine the total length of time the backfire event will take, these two defines determine the upper and lower limits to the time each individual blink (or flicker) will take within the overall backfire event (BFF stands for “back fire flicker.”) In other words, while backfiring the light will blink randomly on and off for some values between BFF_Short and BFF_Long.
Light Settings
Blinking
#define BlinkInterval 378 #define FastBlinkInterval 50
BlinkInterval is a value in milliseconds that sets the blink rate for lights set to “BLINK” or “BLINK_ALT” (for example, turn signals). Recall that 1000 = 1 second. FastBlinkInterval is the value in milliseconds that sets the fast blink rate for lights set to “FASTBLINK” or “FASTBLINK_ALT.”
The “_ALT” versions blink just like the regular versions, but in an alternating fashion - that is, if you have one output set to FASTBLINK, and another to FASTBLINK_ALT, they will each blink at the same rate (FastBlinkInterval) but when one is on the other will be off, and vice-versa. This can be used to create effects such as those seen on police cars, fire trucks, and other emergency vehicles.
Dim
#define DimLevel 50
The level of brightness for the DIM setting, this is a number from 0-255, with 0 being off, 255 being full on. Often numbers much greater than half (128) are hard to distinguish from full on. Experiment to get the number that makes your lights as dim as you want them.
Fadein and Fadeout
#define FadeOutTime 300 #define FadeInTime 50
The length of time the fade in and fade out Settings take, in milliseconds (1000 mS = 1 second). For realism the fade-in time should usually be quite short, but the minimum value is 50 (1/20th of a second). If you set it lower than that, it will automatically be changed to 50 at runtime.
Shelf-Queen Mode
#define enableShelfQueenMode true #define shelfQueenSchemeNumber 2
Shelf-queen mode allows the OSL to operate even without radio signals. You can use this for models that will be put on display (aka, “shelf queens”), just apply power to the OSL without connecting that radio signal wire. If enableShelfQueenMode = true, and the OSL does not detect a radio signal, it will set all lights to their settings in “Pos 1” (first position) of Channel 3 for the scheme number specified (“shelfQueenSchemeNumber”).
NOTE: the shelf-queen check will only happen once at startup. If a radio signal is later detected, the OSL will return to normal operation and it will initialize itself to the prior active scheme regardless of what the shelf queen scheme number is set to below. If the radio signal is lost after that, OSL will go into failsafe mode as usual, it will not attempt to return to shelf-queen mode until the next startup.
NOTE: if you specify a scheme number greater than 1, you need to make sure you have that scheme defined in AA_LIGHT_SETUP!
#define enableShelfQueenDelay true #define sqd_Time_Short 100 #define sqd_Time_Long 6000
We can also add a random delay before the lights come on in shelf queen mode, this may be desirable if you have multiple models on display with a single power source to all of them, the random delay will mean the lights on each model will turn on at a different time. To enable this feature set “enableShelfQueenDelay” to true and then define the range of time within which you want the random delay to occur (“sqd_Time_Short” and “sqd_Time_Long”). If you want the lights to come on immediately, set “enableShelfQueenDelay” to false.
Debugging
define DEBUG false
Set this to true to receive debugging messages out the serial port.
#define LED_DEBUG true
If this is set to true, the Green LED on the board will be on whenever the car is moving forward,
the Red LED will come on whenever the car is moving in reverse,
both LEDs will turn OFF when the car is stopped,
both LEDs will turn ON when the car is braking,
the Red LED will blink if you are turning left, and
the Green LED will blink if you are turning right.
You can use these to verify the board is working correctly without having any external lights connected.
#define BLINK_LIGHTS_RX_LOST false
If true, all eight LED outputs will blink rapidly when the radio signal has been lost. If set to false, only the onboard Red and Green LEDs will blink when the radio signal has been lost.