LightSculpture.h File Reference

#include <Arduino.h>

Go to the source code of this file.

Enumerations
enum	Modes { offMode, lightShowMode, nightLightMode }

Functions
void	delayUsingKnob (int duration)
void	fadeUp (const byte pin, int duration)
void	fadeUpAll (int duration)
void	fadeUpArray (const byte arrayName[], const byte arrayLength, int duration)
void	fadeUpArrayInOrder (const byte arrayName[], const byte arrayLength, int duration)
void	fadeDown (const byte pin, int duration)
void	fadeDownAll (int duration)
void	fadeDownArray (const byte arrayName[], const byte arrayLength, int duration)
void	fadeDownArrayInOrder (const byte arrayName[], const byte arrayLength, int duration)
void	blinkArrayInOrder (const byte arrayName[], const byte arrayLength, int duration)
void	blinkTwoArraysInOrder (const byte array1[], const byte array2[], const byte arrayLength, int duration)
void	fadeUpTwoArraysInOrder (const byte array1[], const byte array2[], const byte arrayLength, int duration)
void	fadeDownTwoArraysInOrder (const byte array1[], const byte array2[], const byte arrayLength, int duration)
void	crossFade (const byte downPin, const byte upPin, int duration)
void	crossFadeArrays (const byte downArrayName[], const byte downArrayLength, const byte upArrayName[], const byte upArrayLength, int duration)
void	setupLightSculpture ()
void	updateMode ()
void	updateOffSwitch ()
void	runNightLight ()
void	pwm (float fractionOn)
void	pwm (const byte pin, float fractionOn)
void	pwm (const byte arrayName[], const byte arrayLength, float fractionOn)
int	getOnTimeUsingFraction (float fractionOn)
void	updateStepSize (int duration)
void	turnOnArray (const byte arrayName[], const byte arrayLength)
void	turnOffArray (const byte arrayName[], const byte arrayLength)
void	turnOnAll ()
void	turnOffAll ()
void	pwmUsingKnob ()
void	updateKnobValue ()
int	getOnTimeUsingKnob ()
float	gammaCorrect (float ratio)

Variables
Modes	mode

Function Documentation

void delayUsingKnob

(

int

duration

)

delayUsingKnob(int duration)

Intended to be used as a replacement for delay(X), however this also allows knob position to scale delay times

If knobValue (knob position) is SMALL just after turning from OFF/ON (pin A5 ~ 1) then delayUsingKnob(100); will behave very similar to delay(100); except that delayUsingKnob(100); can be interrupted by a change in knob state / mode.

If knobValue (knob position) is LARGE rotated 3/4 of a turn after turning from OFF/ON (pin A5 ~ 750) then delayUsingKnob(100); will behave very similar to delay(100); except that delayUsingKnob(100); can be interrupted by a change in knob state / mode.

Example of delayUsingKnob(100); and knobValue is 750 (lightShowMode) updateStepSize(100); modifies fadingStepSize = 1 so the for loop executes 1 times with a delay of 10 milliseconds versus 100 milliseconds

Example of delayUsingKnob(100); and knobValue is 500 (lightShowMode) updateStepSize(100); modifies fadingStepSize = 0.28656716417362976 so the for loop executes 4 times with a delay of 40 milliseconds versus 100 milliseconds

Example of delayUsingKnob(100); and knobValue is 1 (lightShowMode) updateStepSize(100); modifies fadingStepSize = 0.10013037809 so the for loop executes 10 times with a delay of 100 milliseconds as specified

Parameters

duration

void fadeUp	(	const byte	pin,
		int	duration
	)

fadeUp()

Uses PWM to turn on a LED (specified by pin) from 0% PWM to 100% PWM over time (specified by duration)

Like delayUsingKnob() fadeUp() allows knob position to scale the value duration which effectively scales the amount of time it takes to fadeUp() a pin based on the position of the knob (value of pin A5)

In addition - fadeUp() can be interrupted by a change in knob state / mode.

Parameters

pin	- the pin on the arduino to fadeUp
duration	- the time in milliseconds to go from 0% to 100% brightness

void fadeUpAll

(

int

duration

)

fadeUpAll()

Uses PWM to turn on all LED (pins 2 -15 if connected to LEDs) from 0% PWM to 100% PWM over time (specified by duration)

Like delayUsingKnob() fadeUpAll() allows knob position to scale the value duration which effectively scales the amount of time it takes to fadeUpAll() a pin based on the position of the knob (value of pin A5)

In addition - fadeUpAll() can be interrupted by a change in knob state / mode.

Parameters

duration

- the time in milliseconds to go from 0% to 100% brightness

void fadeUpArray	(	const byte	arrayName[],
		const byte	arrayLength,
		int	duration
	)

fadeUpArray()

Uses PWM to turn on the pins connected to LEDs specified in a arrayName from 0% PWM to 100% PWM over time (specified by duration)

Like delayUsingKnob() fadeUpArray() allows knob position to scale the value duration which effectively scales the amount of time it takes to fadeUpArray() a pin based on the position of the knob (value of pin A5)

In addition - fadeUpArray() can be interrupted by a change in knob state / mode.

Parameters

arrayName	- the name of the array to fadeUp - must be declared in YourInitials_LightSculpture.ino as a For example - const byte exampleArray[] = {9, 10, 11, 12, 13, 14, 15};
arrayLength	- the number of elements in arrayName - you can count them or use the example here when calling the function fadeUpArray For example - sizeof(exampleArray)
duration	- the time in milliseconds to go from 0% to 100% brightness

void fadeUpArrayInOrder	(	const byte	arrayName[],
		const byte	arrayLength,
		int	duration
	)

fadeUpArrayInOrder()

Uses PWM to turn on the pins connected to LEDs specified in a arrayName from 0% PWM to 100% PWM over time (specified by duration)

Like delayUsingKnob() fadeUpArrayInOrder() allows knob position to scale the value duration which effectively scales the amount of time it takes to fadeUpArrayInOrder() a pin based on the position of the knob (value of pin A5)

In addition - fadeUpArrayInOrder() can be interrupted by a change in knob state / mode.

The difference between fadeUpArrayInOrder and fadeUpArray is that fadeUpArrayInOrder fades up the each pin in the array individually while fadeUpArray fades up all the pins in an array at the same time.

Parameters

arrayName	- the name of the array to fadeUp - must be declared in YourInitials_LightSculpture.ino as a For example - const byte exampleArray[] = {9, 10, 11, 12, 13, 14, 15};
arrayLength	- the number of elements in arrayName - you can count them or use the example here when calling the function fadeUpArray For example - sizeof(exampleArray)
duration	- the time in milliseconds to go from 0% to 100% brightness

void fadeDown	(	const byte	pin,
		int	duration
	)

fadeDown()

Uses PWM to turn off a LED (specified by pin) from 100% PWM to 0% PWM over time (specified by duration)

Like delayUsingKnob() fadeDown() allows knob position to scale the value duration which effectively scales the amount of time it takes to fadeDown() a pin based on the position of the knob (value of pin A5)

In addition - fadeDown() can be interrupted by a change in knob state / mode.

Parameters

pin	- the pin on the arduino to fadeDown
duration	- the time in milliseconds to go from 100% to 0% brightness

void fadeDownAll

(

int

duration

)

fadeDownAll()

Uses PWM to turn off all LED (pins 2 -15 if connected to LEDs) from 100% PWM to 0% PWM over time (specified by duration)

Like delayUsingKnob() fadeDownAll() allows knob position to scale the value duration which effectively scales the amount of time it takes to fadeDownAll() a pin based on the position of the knob (value of pin A5)

In addition - fadeDownAll() can be interrupted by a change in knob state / mode.

Parameters

duration

- the time in milliseconds to go from 100% to 0% brightness

void fadeDownArray	(	const byte	arrayName[],
		const byte	arrayLength,
		int	duration
	)

fadeDownArray()

Uses PWM to turn off the pins connected to LEDs specified in a arrayName from 100% PWM to 0% PWM over time (specified by duration)

Like delayUsingKnob() fadeDownArray() allows knob position to scale the value duration which effectively scales the amount of time it takes to fadeUpArray() a pin based on the position of the knob (value of pin A5)

In addition - fadeDownArray() can be interrupted by a change in knob state / mode.

Parameters

arrayName	- the name of the array to fadeDown - must be declared in YourInitials_LightSculpture.ino as a For example - const byte exampleArray[] = {9, 10, 11, 12, 13, 14, 15};
arrayLength	- the number of elements in arrayName - you can count them or use the example here when calling the function fadeUpArray For example - sizeof(exampleArray)
duration	- the time in milliseconds to go from 100% to 0% brightness

void fadeDownArrayInOrder	(	const byte	arrayName[],
		const byte	arrayLength,
		int	duration
	)

fadeDownArrayInOrder()

Uses PWM to turn off the pins connected to LEDs specified in a arrayName from 100% PWM to 0% PWM over time (specified by duration)

Like delayUsingKnob() fadeDownArrayInOrder() allows knob position to scale the value duration which effectively scales the amount of time it takes to fadeDownArrayInOrder() a pin based on the position of the knob (value of pin A5)

In addition - fadeDownArrayInOrder() can be interrupted by a change in knob state / mode.

The difference between fadeDownArrayInOrder and fadeDownArray is that fadeDownArrayInOrder fades down each pin in the array individually while fadeDownArray fades down all the pins in an array at the same time.

Parameters

arrayName	- the name of the array to fadDown - must be declared in YourInitials_LightSculpture.ino as a For example - const byte exampleArray[] = {9, 10, 11, 12, 13, 14, 15};
arrayLength	- the number of elements in arrayName - you can count them or use the example here when calling the function fadeUpArray For example - sizeof(exampleArray)
duration	- the time in milliseconds to go from 100% to 0% brightness

void blinkArrayInOrder	(	const byte	arrayName[],
		const byte	arrayLength,
		int	duration
	)

blinkArrayInOrder()

Uses PWM to fadeUp and then fadeDown the pins connected to LEDs specified in a arrayName from 0% PWM to 100% PWM over time (specified by duration)

Like delayUsingKnob() blinkArrayInOrder allows knob position to scale the value duration which effectively scales the amount of time it takes to blinkArrayInOrder() a pin based on the position of the knob (value of pin A5)

In addition - blinkArrayInOrder() can be interrupted by a change in knob state / mode.

Parameters

arrayName	- the name of the array to fadeUp and then fadeDown - must be declared in YourInitials_LightSculpture.ino as a For example - const byte exampleArray[] = {9, 10, 11, 12, 13, 14, 15};
arrayLength	- the number of elements in arrayName - you can count them or use the example here when calling the function fadeUpArray For example - sizeof(exampleArray)
duration	- the time in milliseconds to go from 0% to 100% brightness

void blinkTwoArraysInOrder	(	const byte	array1[],
		const byte	array2[],
		const byte	arrayLength,
		int	duration
	)

blinkTwoArraysInOrder()

Uses PWM to turn fadeUp and then fadeDown the pins connected to LEDs specified in two array arrayName from 0% PWM to 100% PWM over time (specified by duration)

Like delayUsingKnob() blinkTwoArraysInOrder() allows knob position to scale the value duration which effectively scales the amount of time it takes to blinkTwoArraysInOrder() a pin based on the position of the knob (value of pin A5)

In addition - blinkTwoArraysInOrder() can be interrupted by a change in knob state / mode.

Note: array1 and array2 must have the same number of elements.

Parameters

array1	- the name of the first array to fadeUp and then fadeDown - must be declared in YourInitials_LightSculpture.ino as a For example - const byte exampleArray1[] = {9, 10, 11, 12, 13, 14, 15};
array2	- the name of the second array to fadeUp and then fadeDown - must be declared in YourInitials_LightSculpture.ino as a For example - const byte exampleArray2[] = {2, 3, 4, 5, 6, 7, 8};
arrayLength	- the number of elements in arrayName - you can count them or use the example here when calling the function fadeUpArray For example - sizeof(exampleArray)
duration	- the time in milliseconds to go from 0% to 100% brightness

void fadeUpTwoArraysInOrder	(	const byte	array1[],
		const byte	array2[],
		const byte	arrayLength,
		int	duration
	)

fadeUpTwoArraysInOrder()

Uses PWM to turn on the pins connected to LEDs specified in a arrayName from 100% PWM to 0% PWM over time (specified by duration)

Like delayUsingKnob() fadeUpTwoArraysInOrder() allows knob position to scale the value duration which effectively scales the amount of time it takes to fadeUpTwoArraysInOrder() a pin based on the position of the knob (value of pin A5)

In addition - fadeUpTwoArraysInOrder() can be interrupted by a change in knob state / mode.

The difference between fadeUpTwoArraysInOrder and fadeUpTwoArrays is that fadeUpArrayInOrder fades up each pin in the array individually while fadeUpTwoArrays fades up all the pins in an array at the same time.

Note: array1 and array2 must have the same number of elements.

Parameters

array1	- the name of the first array to fadeUp - must be declared in YourInitials_LightSculpture.ino as a For example - const byte exampleArray1[] = {9, 10, 11, 12, 13, 14, 15};
array2	- the name of the second array to fadeUp - must be declared in YourInitials_LightSculpture.ino as a For example - const byte exampleArray2[] = {2, 3, 4, 5, 6, 7, 8};
duration	- the time in milliseconds to go from 100% to 0% brightness

void fadeDownTwoArraysInOrder	(	const byte	array1[],
		const byte	array2[],
		const byte	arrayLength,
		int	duration
	)

fadeDownTwoArraysInOrder()

Uses PWM to turn off the pins connected to LEDs specified in a arrayName from 100% PWM to 0% PWM over time (specified by duration)

Like delayUsingKnob() fadeDownTwoArraysInOrder() allows knob position to scale the value duration which effectively scales the amount of time it takes to fadeDownTwoArraysInOrder() a pin based on the position of the knob (value of pin A5)

In addition - fadeDownTwoArraysInOrder() can be interrupted by a change in knob state / mode.

The difference between fadeDownTwoArraysInOrder and fadeDownTwoArrays is that fadeDownArrayInOrder fades down each pin in the array individually while fadeDownTwoArrays fades down all the pins in an array at the same time.

Note: array1 and array2 must have the same number of elements.

Parameters

array1	- the name of the first array to fadeDown - must be declared in YourInitials_LightSculpture.ino as a For example - const byte exampleArray1[] = {9, 10, 11, 12, 13, 14, 15};
array2	- the name of the second array to fadeDown - must be declared in YourInitials_LightSculpture.ino as a For example - const byte exampleArray2[] = {2, 3, 4, 5, 6, 7, 8};
duration	- the time in milliseconds to go from 100% to 0% brightness

void crossFade	(	const byte	downPin,
		const byte	upPin,
		int	duration
	)

crossFade()

Cross fading allows you to have a pair of LEDs fading in opposite directions. One LED will fade from dark to bright, while at the same time the other LED will fade from bright to dark

crossFade() uses PWM to fade the pins connected to LEDs specified in a downPin and upPin over time (specified by duration)

Like delayUsingKnob() crossFade() allows knob position to scale the value duration which effectively scales the amount of time it takes to crossFade() a pin based on the position of the knob (value of pin A5)

In addition - crossFade() can be interrupted by a change in knob state / mode.

Parameters

downPin	- the number of the pin to fadeDown
upPin	- the number of the pin to fadeUp
duration	- the time in milliseconds to go from 100% to 0% brightness

void crossFadeArrays	(	const byte	downArrayName[],
		const byte	downArrayLength,
		const byte	upArrayName[],
		const byte	upArrayLength,
		int	duration
	)

crossFadeArrays()

Cross fading allows you to have a pair of LEDs fading in opposite directions. One LED will fade from dark to bright, while at the same time the other LED will fade from bright to dark

crossFadeArrays() uses PWM to fade the pins connected to LEDs specified in a downArrayName and upArrayName over time (specified by duration)

Like delayUsingKnob() crossFadeArrays() allows knob position to scale the value duration which effectively scales the amount of time it takes to crossFadeArrays() a array based on the position of the knob (value of pin A5)

In addition - crossFadeArrays() can be interrupted by a change in knob state / mode.

Note: downArrayName and upArrayName must have the same number of elements.

Parameters

downArrayName	- the name of the array to fadeDown - must be declared in YourInitials_LightSculpture.ino as a For example - const byte exampleArray1[] = {9, 10, 11, 12, 13, 14, 15};
downArrayLength	- the number of elements in DownArrayName - you can count them or use the example here when calling the function fadeUpArray For example - sizeof(exampleArray)
upArrayName	the name of the second array to fadeUp - must be declared in YourInitials_LightSculpture.ino as a For example - const byte exampleArray2[] = {2, 3, 4, 5, 6, 7, 8};
upArrayLength	- the number of elements in upArrayName - you can count them or use the example here when calling the function fadeUpArray For example - sizeof(exampleArray)
duration	- the time in milliseconds to go from 100% to 0% brightness

void setupLightSculpture

(

)

setupLightSculpture()

sets up the pinModes of pin 2-15 as OUTPUT

sets up the Potentiometer pin A5 (knobPin) as an INPUT - this will be the pin that we later use a analogRead on

sets up the Potentiometer pin A4 (switchPin) as an INPUT_PULLUP - this will be the pin that we later use a digitalRead on

sets up the serial monitor at 9600 baud

void updateMode

(

)

updateMode()

Used to update the mode or state the light sculpture is running in. The mode is determined by reading the value of pin A5(knobPin) And also reading the value of pin A4 (switchPin)

After these two values are updated then we run through some logic to determine the mode.

void updateOffSwitch

(

)

updateOffSwitch()

Reads the value of pin A4 (switchPin) and sets global variable switchIsOff to that value

When digitalRead(switchPin =A4) if the pin A4 is (HIGH ==1) or at 5V then the light sculpture should be OFF

void runNightLight

(

)

runNightLight()

This function is running when the value on pin A5 is greater than 768. ie nightLightMode

void pwm

(

float

fractionOn

)

pwm(allLedPins)

The function that actually does the software pwm of pins 2-15 Essentially turns all pins on for a very brief period of time then turns them off for a very brief period of time. The amount of time that the LEDs should be on is calculated by the helper function getOnTimeUsingFraction().

Parameters

fractionOn

- the fractional amount the the LEDs should be on - for example if they should be at 50% brightness, then fractionOn should be passed in as 0.50

void pwm	(	const byte	pin,
		float	fractionOn
	)

pwm(aSpecificLedPin)

The function that actually does the software pwm of a LED pin Essentially turns the specified LED pin on for a very brief period of time then turns it off for a very brief period of time. The amount of time that the LED should be on is calculated by the helper function getOnTimeUsingFraction().

Parameters

pin	- the specific LED pin to pwm
fractionOn	- the fractional amount the the LEDs should be on - for example if they should be at 50% brightness, then fractionOn should be passed in as 0.50

void pwm	(	const byte	arrayName[],
		const byte	arrayLength,
		float	fractionOn
	)

pwm(arrayName, arrayLength, fractionOn)

Like pwm(allLedPins) pwm(arrayName)does a software pwm of the LEDs pins specified in arrayName. pwm(arrayName) Essentially turns the specified LED pin on for a very brief period of time then turns it off for a very brief period of time. The amount of time that the LED should be on is calculated by the helper function getOnTimeUsingFraction().

Parameters

arrayName	- the name of the array to pwm - must be declared in YourInitials_LightSculpture.ino as a For example - const byte exampleArray1[] = {9, 10, 11, 12, 13, 14, 15};
arrayLength	- the number of elements in arrayName - you can count them or use the example here when calling the function fadeUpArray For example - sizeof(exampleArray)
fractionOn	- the fractional amount the the LEDs should be on - for example if they should be at 50% brightness, then fractionOn should be passed in as 0.50

int getOnTimeUsingFraction

(

float

fractionOn

)

getOnTimeUsingFraction()

getOnTimeUsingFraction() is a helper function for pwm(). getOnTimeUsingFraction() calculates the time in which the LEDs should be on versus off for pwm().

Parameters

fractionOn

- the fraction of the total time that the LEDs should be on

Returns

returns an int - onTime - that is the gammaCorrected fractionOn multiplied by pwmPeriod - the length of the full pwm() cycle.

void updateStepSize

(

int

duration

)

updateStepSize

Updates global variable fadingStepSize

Example if duration is 100 (used to replace delay(100);) and knobValue is 750 (lightShowMode)

knobRatio = knobValue(750) / nightLightMinValue(768); => 0.9765625 knobRatio = min(knobRatio, maxKnobRatio); => 0.9 stepsOfDuration = duration(100) * (1 - knobRatio(0.9) / msPerStep(10); stepsOfDuration = 100 * (1 - 0.9) / 10; stepsOfDuration = 100 * (0.1) / 10; stepsOfDuration = 10 / 10; stepsOfDuration = 1; fadingStepSize = 1 / stepsOfDuration; => 1 For loop would repeat 1 times for a delay of delay(10)

Example if duration is 100 (used to replace delay(100);) and knobValue is 500 (lightShowMode)

knobRatio = knobValue(500) / nightLightMinValue(768); => 0.65104166666 knobRatio = min(knobRatio, maxKnobRatio); => 0.65104166666 stepsOfDuration = duration(100) * (1 - knobRatio(0.65104166666) / msPerStep(10); stepsOfDuration = 100 * (1 - 0.65104166666) / 10; stepsOfDuration = 100 * (0.34895833334) / 10; stepsOfDuration = 34.895833334 / 10; stepsOfDuration = 3.4895833334; fadingStepSize = 1 / stepsOfDuration; => 0.28656716417362976 For loop would repeat 4 times for a delay of delay(40)

Example if duration is 100 (used to replace delay(100);) and knobValue is 1 (lightShowMode)

knobRatio = knobValue(1) / nightLightMinValue(768); => 0.00130208333 knobRatio = min(knobRatio, maxKnobRatio); => 0.00130208333 stepsOfDuration = duration(100) * (1 - knobRatio(0.00130208333) / msPerStep(10); stepsOfDuration = 100 * (1 - 0.00130208333) / 10; stepsOfDuration = 100 * (0.99869791667) / 10; stepsOfDuration = 99.869791667 / 10; stepsOfDuration = 9.9869791667; fadingStepSize = 1 / stepsOfDuration; => 0.10013037809 For loop would repeat 10 times for a delay of delay(40)

Parameters

duration

void turnOnArray	(	const byte	arrayName[],
		const byte	arrayLength
	)

turnOnArray()

Turns on LEDs connected to pins specified in arrayName at full brightness with no delay

Parameters

arrayName	- the name of the array to turnOn - must be declared in YourInitials_LightSculpture.ino as a For example - const byte exampleArray1[] = {9, 10, 11, 12, 13, 14, 15};
arrayLength	- the number of elements in arrayName - you can count them or use the example here when calling the function fadeUpArray For example - sizeof(exampleArray)

void turnOffArray	(	const byte	arrayName[],
		const byte	arrayLength
	)

turnOffArray()

Turns off LEDs connected to pins specified in arrayName with no delay

Parameters

arrayName	- the name of the array to turnOff - must be declared in YourInitials_LightSculpture.ino as a For example - const byte exampleArray1[] = {9, 10, 11, 12, 13, 14, 15};
arrayLength	- the number of elements in arrayName - you can count them or use the example here when calling the function fadeUpArray For example - sizeof(exampleArray)

void turnOnAll

(

)

turnOnAll()

Turns on LEDs connected to pins 2-15 at full brightness with no delay

void turnOffAll

(

)

turnOffAll()

Turns off LEDs connected to pins 2-15 with no delay

void pwmUsingKnob

(

)

pwmUsingKnob()

void updateKnobValue

(

)

updateKnobValue()

Performs an analogRead of pin A5 on the Arduino which is connected to the Potentiometer and stores that value in the global variable knobValue.

int getOnTimeUsingKnob

(

)

getOnTimeUsingKnob()

Calculates the amount of time a LED should be on versus off based on the position of the potentiometer knob. This function allows the program to update its delay(onTime) based on the position of the potentiometer knob.

Returns

- Returns the integer value onTime which could be passed to delayUsingKnob(OnTime)

float gammaCorrect

(

float

ratio

)

gammaCorrect()

gammaCorrect() attempts to adjust the fading to values which human eyes can see. If we were to create pwm values across the full range of values, many changes in those pwm values would result in changes we could not see with our eyes. Hence the brightness change from low to high or high to low would be seem non linear.

Parameters

ratio

- the number which your desire to rise to the 3rd power

Returns

float - product which is the value of ratio raised to the 3rd power