=====Sun Clock and Sun Angle=====

These two user-scripts provide some timing properties that can be used to create triggers and conditions based on the suns position. For instance, we want to turn on or off some lights or change the content depending on the incoming daylight or position of the sun. 
The SunClock script have three predefined properties, Sunset, Sunrise and Daylight. It is also possible to define [[blocks:app-note:sunclock#define_a_custom_time_property|custom timing properties]] as required. 


===== Installation =====

You need a computer with a running blocks server and a web browser to use this application note.

Here's a PIXILAB-blocks-root folder containing everything you need for this application
{{ :blocks:app-note:sunclock:sunclock-root.zip |Download this ZIP file and unpack it}} then follow the instructions in the [[blocks:app-note:start|general setup section]].
The userscripts is also available from [https://github.com/pixilab/blocks-script|the script repository in GitHub]]. Merge the complete script directory to make sure you get the latest script base and any dependencies. 

Once you've done the general setup, copied the files and pointed your Blocks server to this root folder, follow these steps to run this application:

  - Start Blocks.
  - Open the editor using the Admin button.
  - Log in using the name admin and the password pixi.

 

====Configure the systems position====
 
For the script to be able to calculate the suns position, we must provide the systems geographical position. That is done from a task that runs automatically on server start-up. 

{{:blocks:app-note:sunclock:setposition.png?800|}}

To find out the longitude and latitude for a certain spot one can use a map service, in the case of [[https://www.google.com/maps|Google Maps]], it is possible to right click in a location to see this. It is presented in the order latitude, longitude.

{{:blocks:app-note:sunclock:googlemaps.png?800|}}

There are also web services that does similar thing, i.e. [[https://www.latlong.net/]]
=====Define a custom time property=====

The calculations is done with the suncalc.js library stored in the script/lib directory. (https://github.com/mourner/suncalc)

To define a custom timing in blocks, create a task that runs automatically at server start-up. Add a do statement and target the SunClock.defineCustom. 

{{:blocks:app-note:sunclock:customproperty.png?800|}}

This example uses //solarNoon// for both startMoment and endMoment but with different offsets. This property will be True 5 minutes before noon and remain true until 10 minutes after noon (15 minutes), it is also possible to offset with in example -5 minutes. 

The script can handle the following startMoments, definitions in bold can be used as //startMoment// and //endMoment//,

**sunrise**	sunrise (top edge of the sun appears on the horizon)

**sunriseEnd**	sunrise ends (bottom edge of the sun touches the horizon)

**goldenHourEnd**	morning golden hour (soft light, best time for photography) ends

**solarNoon**	solar noon (sun is in the highest position)

**goldenHour**	evening golden hour starts

**sunsetStart**	sunset starts (bottom edge of the sun touches the horizon)

**sunset**	sunset (sun disappears below the horizon, evening civil twilight starts)

**dusk**	dusk (evening nautical twilight starts)

**nauticalDusk**	nautical dusk (evening astronomical twilight starts)

**night**	night starts (dark enough for astronomical observations)

**nadir**	nadir (darkest moment of the night, sun is in the lowest position)

**nightEnd**	night ends (morning astronomical twilight starts)

**nauticalDawn**	nautical dawn (morning nautical twilight starts)

**dawn**	dawn (morning nautical twilight ends, morning civil twilight starts)

=====Set up a test=====

The provided root contains a task that writes to the log every time the value of the custom property changes. 
This task uses the custom property FiveMinutesToNoon as a trigger and all it does is to log the value of the trigger. 
Remember that the definition of Noon is when the sun is at its highest position, hence it will vary over the year. 
'
{{:blocks:app-note:sunclock:testlogtask.png?800|}}


=====Sun Angle=====

The SunAngle scripts provides two properties Altitude and Azimuth. 

Altitude represents the sun altitude above the horizon in radians, 0 at the horizon and 1 at the zenith (straight over your head) Please not this property can have a negative value.
azimuth: sun azimuth in radians (direction along the horizon, measured from south to west), 0 is south and 1 is northwest.

The Sun Angle must be configured with a position just like we do for the Sun Clock. This is done from a task the sets the longitude and latitude properties. Setup tasks like this one is often suitable to trigger automatically from Server Startup.

{{:blocks:app-note:sunclock:setpositionsunangle.png|}}

There is also a task where we can see the values whenever the altitude property changes.  (Once every minute)

{{:blocks:app-note:sunclock:sunanglelog.png|}}