{"_id":"59acd2428680a3003977cbd7","project":"5581248904ae5b0d0026289a","version":{"_id":"57fdb17c4defec0e0064228b","project":"5581248904ae5b0d0026289a","__v":2,"createdAt":"2016-10-12T03:43:56.009Z","releaseDate":"2016-10-12T03:43:56.009Z","categories":["57fdb17c4defec0e0064228c","57fdb17c4defec0e0064228d","57fdb17c4defec0e0064228e","57fdb520bcc07b0e00d1ef41"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2.0"},"category":{"_id":"57fdb520bcc07b0e00d1ef41","__v":0,"project":"5581248904ae5b0d0026289a","version":"57fdb17c4defec0e0064228b","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-10-12T03:59:28.475Z","from_sync":false,"order":1,"slug":"guides","title":"Guides"},"user":"557e2561eb75d80d00af3dab","githubsync":"","__v":1,"parentDoc":null,"updates":["59d76f1ccd50a8003ed46076"],"next":{"pages":[],"description":""},"createdAt":"2017-09-04T04:10:42.259Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":6,"body":"The LIFX LAN protocol supports changing the color of a bulb over time in accordance with the shape of a waveform.\n\nThese waveforms allow us to  combine functions such as fading, pulsing, etc by applying waveform interpolation on the modulation between two colors.\n\nThe available waveform values are as follows:\n\n| Field | Value |\n|-------|------|\n| SAW | 0 |\n| SINE | 1 |\n| HALF_SINE | 2 |\n| TRIANGLE | 3 |\n| PULSE | 4 |\n\n## Explaining the waveforms\n\nNote that if ``transient == true`` or the waveform is ``SINE`` or ``TRIANGLE`` then the device will return to the original colour after the effect. Otherwise the device will not revert to the original colour after the effect.\n\nThe waveform types can be best explained with the following images:\n\n### SINE\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/4058e6f-lifx_waveform_model.jpg\",\n        \"lifx_waveform_model.jpg\",\n        1073,\n        187,\n        \"#201e37\"\n      ]\n    }\n  ]\n}\n[/block]\n* Where ``waveform == SINE``, the color will cycle smoothly from current color   to ``color`` and then end back at current color\n* The duration of one cycle will last for ``period`` milliseconds\n\n### PULSE\n\nPulse waveforms use the ``skew_ratio`` parameter:\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/350af02-lifx_waveform_pulse_default.jpg\",\n        \"lifx_waveform_pulse_default.jpg\",\n        1072,\n        191,\n        \"#0f0c24\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/d99efbb-lifx_waveform_pulse_025.jpg\",\n        \"lifx_waveform_pulse_025.jpg\",\n        1074,\n        186,\n        \"#232037\"\n      ]\n    }\n  ]\n}\n[/block]\nWhere ``waveform == PULSE``, the color will be set immediately to ``color``,  then to current color after the duty cycle fraction expires\n\nThe duty cycle percentage is calculated by applying ``1 - skew_ratio`` as a percentage of the ``cycle`` duration and changes the time spent on the original colour vs the new colour\n\n*  ``duty_cycle == 0.5``: color will be set to ``color`` for the first 50% of the cycle period, then to current color until the end of the cycle\n\n* ``duty_cycle == 0.25``: color will be set to ``color`` for the first 25% of the cycle period, then to current color until the end of the cycle\n\nNote that skew_ratio in the message is a signed Int16 that is scaled from 0 to 1.\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"value in message\",\n    \"h-1\": \"scaled skew_ratio\",\n    \"0-0\": \"-32768\",\n    \"0-1\": \"0\",\n    \"1-0\": \"-16383\",\n    \"1-1\": \"0.25\",\n    \"2-0\": \"0\",\n    \"2-1\": \"0.5\",\n    \"3-0\": \"16383\",\n    \"3-1\": \"0.75\",\n    \"4-0\": \"32767\",\n    \"4-1\": \"1\"\n  },\n  \"cols\": 2,\n  \"rows\": 5\n}\n[/block]\n### Half-sine\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/83bec78-lifx_waveform_halfsine.jpg\",\n        \"lifx_waveform_halfsine.jpg\",\n        1076,\n        123,\n        \"#28282d\"\n      ]\n    }\n  ]\n}\n[/block]\n* ``waveform == HALF_SINE```: light interpolates smoothly from current color to  ``color``\n* Duration of each cycle lasts for ``period`` milliseconds\n\n### Triangle\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/e230292-lifx_waveform_triangle.jpg\",\n        \"lifx_waveform_triangle.jpg\",\n        1076,\n        123,\n        \"#101015\"\n      ]\n    }\n  ]\n}\n[/block]\n\n* ``waveform == TRIANGLE``: light interpolates linearly from current color to  ``color``, then back to current color\n* Duration of each cycle lasts for ``period`` milliseconds\n\n### Saw\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/e3fc6b5-lifx_waveform_saw.jpg\",\n        \"lifx_waveform_saw.jpg\",\n        1076,\n        123,\n        \"#15121a\"\n      ]\n    }\n  ]\n}\n[/block]\n* ``waveform == Saw``: light interpolates linearly from current color to ``color``\n* Duration of each cycle lasts for ``period`` milliseconds","excerpt":"","slug":"waveforms","type":"basic","title":"Waveforms"}
The LIFX LAN protocol supports changing the color of a bulb over time in accordance with the shape of a waveform. These waveforms allow us to combine functions such as fading, pulsing, etc by applying waveform interpolation on the modulation between two colors. The available waveform values are as follows: | Field | Value | |-------|------| | SAW | 0 | | SINE | 1 | | HALF_SINE | 2 | | TRIANGLE | 3 | | PULSE | 4 | ## Explaining the waveforms Note that if ``transient == true`` or the waveform is ``SINE`` or ``TRIANGLE`` then the device will return to the original colour after the effect. Otherwise the device will not revert to the original colour after the effect. The waveform types can be best explained with the following images: ### SINE [block:image] { "images": [ { "image": [ "https://files.readme.io/4058e6f-lifx_waveform_model.jpg", "lifx_waveform_model.jpg", 1073, 187, "#201e37" ] } ] } [/block] * Where ``waveform == SINE``, the color will cycle smoothly from current color to ``color`` and then end back at current color * The duration of one cycle will last for ``period`` milliseconds ### PULSE Pulse waveforms use the ``skew_ratio`` parameter: [block:image] { "images": [ { "image": [ "https://files.readme.io/350af02-lifx_waveform_pulse_default.jpg", "lifx_waveform_pulse_default.jpg", 1072, 191, "#0f0c24" ] } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/d99efbb-lifx_waveform_pulse_025.jpg", "lifx_waveform_pulse_025.jpg", 1074, 186, "#232037" ] } ] } [/block] Where ``waveform == PULSE``, the color will be set immediately to ``color``, then to current color after the duty cycle fraction expires The duty cycle percentage is calculated by applying ``1 - skew_ratio`` as a percentage of the ``cycle`` duration and changes the time spent on the original colour vs the new colour * ``duty_cycle == 0.5``: color will be set to ``color`` for the first 50% of the cycle period, then to current color until the end of the cycle * ``duty_cycle == 0.25``: color will be set to ``color`` for the first 25% of the cycle period, then to current color until the end of the cycle Note that skew_ratio in the message is a signed Int16 that is scaled from 0 to 1. [block:parameters] { "data": { "h-0": "value in message", "h-1": "scaled skew_ratio", "0-0": "-32768", "0-1": "0", "1-0": "-16383", "1-1": "0.25", "2-0": "0", "2-1": "0.5", "3-0": "16383", "3-1": "0.75", "4-0": "32767", "4-1": "1" }, "cols": 2, "rows": 5 } [/block] ### Half-sine [block:image] { "images": [ { "image": [ "https://files.readme.io/83bec78-lifx_waveform_halfsine.jpg", "lifx_waveform_halfsine.jpg", 1076, 123, "#28282d" ] } ] } [/block] * ``waveform == HALF_SINE```: light interpolates smoothly from current color to ``color`` * Duration of each cycle lasts for ``period`` milliseconds ### Triangle [block:image] { "images": [ { "image": [ "https://files.readme.io/e230292-lifx_waveform_triangle.jpg", "lifx_waveform_triangle.jpg", 1076, 123, "#101015" ] } ] } [/block] * ``waveform == TRIANGLE``: light interpolates linearly from current color to ``color``, then back to current color * Duration of each cycle lasts for ``period`` milliseconds ### Saw [block:image] { "images": [ { "image": [ "https://files.readme.io/e3fc6b5-lifx_waveform_saw.jpg", "lifx_waveform_saw.jpg", 1076, 123, "#15121a" ] } ] } [/block] * ``waveform == Saw``: light interpolates linearly from current color to ``color`` * Duration of each cycle lasts for ``period`` milliseconds