TimeGiver is a highly-customizable circadian lighting rhythm generator that empowers connected lighting systems to support a healthy cycle of sleep and wakefulness by taking arguments such as wake time and sunset length and returning an appropriate set of
TimeGiver is an open-source, highly-customizable circadian lighting rhythm generator that empowers connected lighting systems to support a healthy cycle of sleep and wakefulness. It takes arguments such as wake time and sunset length and returns an appropriate set of lighting parameters such as brightness and color temperature for the current moment. Rhythms can be generated based on just a few parameters using appropriate defaults or customized extensively according to desired maximums, minimums, rates of change, and slope shapes. TimeGiver also includes a sunlight simulator that mimics the natural blue-yellow color gradient of sunlight, producing a unique combination of colors for every time of day that recreates everything from the crisp blues of noontime to the golden hues of late afternoon and mellow blues of dusk, all without compromising color rendering. The project includes both python and javascript implementations as well as a Node.JS module, allowing TimeGiver to serve as part of the back-end of almost any connected lighting project.
Check out our live rhythm visualizer on GitHub Pages that demonstrates the power of TimeGiver's framework.
TimeGiver is based on the research and development work of Timothy Lee, a 3rd-year medical student at Mayo Clinic Alix School of Medicine with strong interests in circadian rhythm disorders and the importance of regular, restorative sleep to good mental health. Questions and comments can be directed to Timothy Lee on Github @timotheonpaulonlee on Github or via LinkedIn.
TimeGiver is an open-source, highly-customizable circadian lighting schedule generator with implementations in python and javascript built to serve as part of the backend for connected lighting systems. The core of the system is the function TimeGiver() that takes arguments that describe a lighting rhythm and returns appropriate lighting parameters for the current or specified time under that rhythm. The code has significant in-line documentation, so this text will focus on a conceptual understanding of the different arguments and return parameters.
TimeGiver accepts over 40 different arguments that describe aspects of how a rhythm is generated, allowing for extensive customization. However, changes in most of the arguments have a minor effect on the final rhythm and all of them come with default values that should be acceptable for most users. As a result, the number of arguments you will want to expose as settings depends on your user base and how they value customizability versus simplicity. There are several core arguments such as wake time and bed time that should be exposed as settings in nearly all applications, and I have bolded them. The arguments are the same across both implementations, though the syntax for passing them is different. Some of the arguments serve for any use of TimeGiver and others only matter when using the blue-yellow sunlight simulator feature. The arguments can also be divided into several different types: those that set key times, those that describe maximums and minimums that fence the rhythms in, those that describes lengths of change, and those that describe slopes of change. The arguments will be grouped according to whether they are general-purpose or specific to the sunrise simulator and then according to their general category as above.
time is a simulated time variable that overrides real current time if it is defined. It is only intended to be used for testing and validation purposes.
wake_time is the time you intend to be awake and ready to start your day in minutes after midnight, and there should be at least 8 hours (480 minutes) of sleep time after bed_time and before wake_time.
bed_time is the time you intend to be in bed with your head on the pillow in minutes after midnight.
wake_offset is how soon before your intended wake up time your lights should start rising and may need to be as high as 45 minutes for heavy sleepers or as low as 5 minutes for light sleepers. This variable is likely to confuse ordinary users and should probably be exposed through a binary questions such as "Are you a heavy sleeper?"
bed_offset is how soon before your intended bed time your lights reach nightlight level and may need to be as high as an hour for hard sleepers or as low as 0 for easy sleepers. This variable is likely to confuse ordinary users and should probably be exposed through a binary questions such as "Do you typically fall asleep easily?"
max_bright is the maximum brightness as a decimal that a light can take at midday and should be 1 under almost all circumstances except perhaps for overpowered lighting designs.
min_bright is the minimum brightness a light should reach around bed time and should be just bright enough to allow you to function safely in a space. Think of this as your nighttime snack, getting up to use the bathroom nightlight level.
max_CCT is the maximum color temperature in kelvins that a light should reach at midday and should generally correspond to the maximum the lighting system can attain with full brightness, unless you find that white uncomfortably cool.
min_CCT is the minimum color temperature in kelvins that a light should reach in the early morning and at bedtime and should generally correspond to the minimum the lighting system can attain, unless you find that white uncomfortably warm.
rise_length_bright is the length of the morning sunrise routine for brightness change and should usually be between 30 minutes and 1 hour to simulate the fast increase in brightness that happens around sunrise and support a quick, painless transition to wakefulness. This argument can also accept fractions of half day length in a string with the form "0.5x", which would set the argument to 1/4th of the total time between wakening and going to bed.
set_length_bright is the length of the evening sunset routine for brightness change and should usually be between 2 and 3 hours to simulate the gradual decrease in brightness that happens around sunset and dusk and support a gradual transition to sleepiness at bedtime. This argument can also accept fractions of half day length in a string with the form "0.5x", which would set the argument to 1/4th of the total day length.
rise_length_CCT is the length of the morning increase in color temperature in minutes. The default value sets it to run for the entire first half of the day, but values values less than half the day make for a more dramatic morning change with a more restful midday. This argument can also accept fractions of half day length in a string with the form "0.5x", which would set the argument to 1/4th of the total day length.
set_length_CCT is the length of the evening decrease in color temperature in minutes. The default value sets it to run for the entire second half of the day, but values values less than half the day make for a more dramatic evening change with a more restful midday. This argument can also accept fractions of half day length in a string with the form "0.5x", which would set the argument to 1/4th of the total day length.
rise_slope_bright describes the slope at which brightness increases in the morning. 0 makes for a perfectly smooth change with a flat slope. values approaching 100 make for a change that happens very quickly and then plateaus. Intermediate positive numbers can be used to mimic exponential changes that happen during sunrise and sunset. Negative numbers simulate a change that starts out gradually and accelerates over time.
set_slope_bright describes the slope at which brightness decreases in the evening. 0 makes for a perfectly smooth change with a flat slope. values approaching 100 make for a change that happens very quickly and then plateaus. Intermediate positive numbers can be used to mimic exponential changes that happen during sunrise and sunset. Negative numbers simulate a change that starts out gradually and accelerates over time.
rise_slope_CCT describes the slope at which color temperature increases in the morning. 0 makes for a perfectly smooth change with a flat slope. values approaching 100 make for a change that happens very quickly and then plateaus. Intermediate positive numbers can be used to mimic exponential changes that happen during sunrise and sunset. Negative numbers simulate a change that starts out gradually and accelerates over time.
set_slope_CCT describes the slope at which color temperature decreases in the evening. 0 makes for a perfectly smooth change with a flat slope. values approaching 100 make for a change that happens very quickly and then plateaus. Intermediate positive numbers can be used to mimic exponential changes that happen during sunrise and sunset. Negative numbers simulate a change that starts out gradually and accelerates over time.
max_scatdist is the maximum difference between the central white point and the warm white point when using the blue-yellow feature. Higher numbers make for deeper blues and warmer whites, especially around midday, but a number too high can impair color rendering, especially with low max_CCT, because color temperature is not defined below 1000K
min_scatdist is the minimum difference between the central white point and the warm white point when using the blue-yellow feature. Higher numbers make for deeper blues and warmer whites, especially around bedtime, but a number too high can impair color rendering, especially with low min_CCT, because color temperature is not defined below 1000K
max_scatangshift is the maximum angle in degrees by which the warm white is shifted up toward yellow and the blue point is shifted down toward a more purple blue when using the blue-yellow feature during sunrise or sunset. Higher numbers make for more yellow sunsets with dusky blue accents while lower numbers make for more orange sunsets with more aqua accents. Numbers too high can lead to very pink sunrises and sunsets with greenish accents.
min_scatangshift is the maximum angle in degrees by which the warm white is shifted up and the blue point is shifted down when using the blue-yellow feature during midday. Higher numbers make for more yellow tinting with dusky blue accents around midday while lower numbers make for more neutral tinting during midday. This should be 0 under most circumstances, unless you are simulating sunlight near a wildfire
max_bright_yellow is the maximum brightness as a decimal that a yellow light using the blue-yellow feature can take at midday and should be 1 under almost all circumstances except for overpowered lighting designs
min_bright_yellow is the minimum brightness a yellow light using the blue yellow feature should reach around bed time and should be just bright enough to allow you to function safely in a space
max_bright_blue is the maximum brightness as a decimal that a blue light using the blue-yellow feature can take at midday and should be 1 under almost all circumstances except for overpowered lighting designs
min_bright_blue is the minimum brightness a blue light using the blue yellow feature should reach around bed time and should be just bright enough to allow you to function safely in a space
rise_length_scatdist is the length in minutes of the morning increase in the distance between the white and warm white points when using the blue-yellow feature. The default value of None or Null sets it to run for the entire second half of the day, but values less than half the day make for a more dramatic morning change with a more restful midday. This argument can accept fractions of half day length in a string with the form "0.5x", which would set the argument to 1/4th of the total day length. It can also accept None or null, in which case it will be set to half of the day length.
rise_length_scatdist is the length in minutes of the evening decrease in the distance between the white and warm white points when using the blue-yellow feature. The default value of None or Null sets it to run for the entire second half of the day, but values less than half the day make for a more dramatic evening change with a more restful midday. This argument can accept fractions of half day length in a string with the form "0.5x", which would set the argument to 1/4th of the total day length. It can also accept None or null, in which case it will be set to half of the day length.
rise_length_scatangshift is the length in minutes of the morning increase in angle by which the warm white point is shifted upward and the blue point shifted downward during sunrise. Higher numbers will make for long, sunrises followed by dramatic golden hours, while lower numbers will make for shorter, more forceful sunrises. This argument can also accept fractions of half day length in a string with the form "0.5x", which would set the argument to 1/4th of the total day length. It can also accept None or null, in which case it will be set to half of the day length.
set_length_scatangshift is the length in minutes of the morning increase in angle by which the warm white point is shifted upward and the blue point shifted downward during sunrise. Higher numbers will make for long, sunsets preceeded by dramatic golden hours, while lower numbers will make for shorter, more forceful sunsets. This argument can also accept fractions of half day length in a string with the form "0.5x", which would set the argument to 1/4th of the total day length. It can also accept None or null, in which case it will be set to half of the day length.
rise_length_bright_yellow is the length of the morning sunrise routine for brightness change in yellow lights when using the blue-yellow feature and should usually be between 30 minutes and 1 hour to simulate the fast increase in brightness that happens around sunrise. This can be changed relative to set_length_bright_blue, making this one shorter than that to emphasize yellows in the golden hour or longer than that to emphasize blues at dawn. This argument can also accept fractions of half day length in a string with the form "0.5x", which would set the argument to 1/4th of the total day length. It can also accept None or null, in which case it will be set to half of the day length.
set_length_bright_yellow is the length of the evening sunset routine for brightness change in yellow lights when using the blue-yellow feature and should usually be between 2 and 3 hours to simulate the gradual decrease in brightness that happens around sunset and dusk, supporting a gradual transition to sleepiness at bedtime. This can be changed relative to set_length_bright_blue, making this one shorter than that to emphasize yellows in the golden hour or longer than that to emphasize blues at dusk. This argument can also accept fractions of half day length in a string with the form "0.5x", which would set the argument to 1/4th of the total day length. It can also accept None or null, in which case it will be set to half of the day length.
rise_length_bright_blue is the length of the morning sunrise routine for brightness change in blue lights when using the blue-yellow feature and should usually be between 30 minutes and 1 hour to simulate the fast increase in brightness that happens around sunrise. This can be changed relative to set_length_bright_blue, making this one longer than that to emphasize yellows in the golden hour or shorter than that to emphasize blues at dawn. This argument can also accept fractions of half day length in a string with the form "0.5x", which would set the argument to 1/4th of the total day length. It can also accept None or null, in which case it will be set to half of the day length.
set_length_bright_blue is the length of the evening sunset routine for brightness change in blue lights when using the blue-yellow feature and should usually be between 1 and 1.5 hours to simulate the gradual decrease in brightness that happens around sunset and dusk, supporting a gradual transition to sleepiness at bedtime. This can be changed relative to set_length_bright_yellow, making this one longer than that to emphasize yellows in the golden hour or shorter than that to emphasize blues at dusk. This argument can also accept fractions of half day length in a string with the form "0.5x", which would set the argument to 1/4th of the total day length. It can also accept None or null, in which case it will be set to half of the day length.
rise_slope_scatdist describes the slope at which the distance between the central white and the warm white increases in the morning when using the blue-yellow feature. 0 makes for a perfectly smooth change with a flat slope and 100 makes for a change that happens very quickly and then plateaus, while numbers inbetween can be used to mimic exponential changes that happen during sunrise and sunset.
set_slope_scatdist describes the slope at which the distance between the central white and the warm white decreases in the evening when using the blue-yellow feature. 0 makes for a perfectly smooth change with a flat slope and 100 makes for a change that happens very quickly and then plateaus, while numbers inbetween can be used to mimic exponential changes that happen during sunrise and sunset.
rise_slope_scatangshift describes the slope at which the angle by which the blue and warm white points are shifted while using the blue-yellow feature decreases over the course of the morning. 0 makes for a perfectly smooth change with a flat slope and 100 makes for a change that happens very quickly and then plateaus, while numbers inbetween can be used to mimic exponential changes that happen during sunrise and sunset.
set_slope_scatangshift describes the slope at which the angle by which the blue and warm white points are shifted while using the blue-yellow feature decreases over the course of the morning. 0 makes for a perfectly smooth change with a flat slope and 100 makes for a change that happens very quickly and then plateaus, while numbers inbetween can be used to mimic exponential changes that happen during sunrise and sunset.
rise_slope_bright_yellow describes the slope at which brightness of a yellow light increases in the morning while using the blue-yellow feature. 0 makes for a perfectly smooth change with a flat slope and 100 makes for a change that happens very quickly and then plateaus, while numbers inbetween can be used to mimic exponential changes that happen during sunrise and sunset.
set_slope_bright_yellow describes the slope at which brightness of a yellow light decreases in the evening while using the blue-yellow feature. 0 makes for a perfectly smooth change with a flat slope and 100 makes for a change that happens very quickly and then plateaus, while numbers inbetween can be used to mimic exponential changes that happen during sunrise and sunset.
rise_slope_bright_blue describes the slope at which brightness of a blue light increases in the morning while using the blue-yellow feature. 0 makes for a perfectly smooth change with a flat slope and 100 makes for a change that happens very quickly and then plateaus, while numbers inbetween can be used to mimic exponential changes that happen during sunrise and sunset.
set_slope_bright_blue describes the slope at which brightness of a blue light decreases in the evening while using the blue-yellow feature. 0 makes for a perfectly smooth change with a flat slope and 100 makes for a change that happens very quickly and then plateaus, while numbers inbetween can be used to mimic exponential changes that happen during sunrise and sunset.
Now that you have reviewed the arguments TimeGiver accepts to build a schedule, it is important to understand how TimeGiver returns lighting parameters. The implementation is different between the implementations, with parameters returned as a list in python and an object literal in javascript and Node.JS, but the variables should be identical across implementations. There are 10 parameters returned in all instances, 4 of which may be relevant for any purpose and 6 of which are only relevant when using the blue-yellow sunlight simulator feature. Note that all variables are returned in every situation and it is your job to decide how to give your users choice over which set of parameters to implement. The ten return variables are:
Now that you are familiar with TimeGiver's arguments and returns, the actual usage of the program is quite straightforward but differs slightly between implementations.
from TimeGiver import TimeGiver
lighting_parameters = TimeGiver (bed_time = "1260", wake_time = "360")
bright_int_ret = lighting_parameters[0]
CCT_mired_int_ret = lighting_parameters[1]
bright_yellow_int_ret = lighting_parameters[2]
bright_blue_int_ret = lighting_parameters[3]
white_x_ret = lighting_parameters[4]
white_y_ret = lighting_parameters[5]
yellow_x_shifted_ret = lighting_parameters[6]
yellow_y_shifted_ret = lighting_parameters[7]
blue_x_shifted_ret = lighting_parameters[8]
blue_y_shifted_ret = lighting_parameters[9]
<script type="text/javascript" src="TimeGiver.js"></script>
let lighting_parameters = TimeGiver({wake_time: 360, bed_time: 1260})
lighting_parameters.blue_x_shifted_ret
npm install timegiver
var parameters = require('TimeGiver');
let lighting_parameters = parameters.TimeGiver(time = 580);
lighting_parameters.blue_x_shifted_ret
FAQs
TimeGiver is a highly-customizable circadian lighting rhythm generator that empowers connected lighting systems to support a healthy cycle of sleep and wakefulness by taking arguments such as wake time and sunset length and returning an appropriate set of
We found that timegiver demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.