Overview
Contents
Overview#
How to cite MoonShine
Poon, L., Jenks, I. T., Crampton, W. G. R. (2024). MoonShine: A software-hardware system for simulating moonlight ground illuminance and re-creating artificial moonlight cycles in a laboratory environment. Methods in Ecology and Evolution. 15: 701-715. https://doi.org/10.1111/2041-210X.14299
The MoonShine system#
MoonShine is an open-source software-hardware system for predicting natural ground illuminance from moonlight, twilight, and sunlight, and for re-creating natural or experimentally manipulated light cycles in laboratory environments using LED arrays.
MoonShine comprises two main software components: MoonShineR and MoonShineP.
MoonShineR consists of an R package and two additional stand-alone R scheduler scripts, each serving a different purpose.
This instruction manual describes the operation of the MoonShineR package, the two stand-alone scheduler scripts, and the MoonShineP software and hardware.
MoonShineR#
The MoonShineR R package predicts ground illuminance (in lux) from moonlight, twilight, and sunlight for specified geographical locations and time periods. It can be used independently of the laboratory light-recreation system and is particularly useful for ecological studies requiring natural light levels as quantitative predictor variables. The MoonShineR package is available through CRAN and should be installed directly from R:
install.packages("MoonShineR")
The R package’s source code is maintained in MoonShineR_package GitHub repository.
The two stand-alone MoonShineR scheduler scripts provide additional functionality for generating LED control schedules for use with MoonShineP. These scripts are not included in the CRAN package and are available from the main MoonShine GitHub repository.
MoonShineR: Moonlight scheduler predicts moonlight illuminance and converts these predictions into LED intensity values, generating an
LED_schedule_moon.csvfile for MoonShineP.MoonShineR: Sunlight/twilight scheduler predicts sunlight and twilight illuminance and converts these predictions into LED intensity values, generating an
LED_schedule_sun.csvfile for MoonShineP.
MoonShineP#
MoonShineP is a Python program running on a Raspberry Pi computer that reads these schedule files and controls arrays of individually addressable LEDs. This allows natural or experimentally manipulated moonlight, sunlight, and twilight cycles to be re-created in laboratory environments.
MoonShineP controls LEDs for recreating realistic moonlight, twilight, and sunlight regimes in a laboratory setting. A light regime can be freely edited, making it ideal for experiments requiring a specific lighting scenario. MoonShineP runs a Python program on the Linux operating system of a Raspberry Pi computer to control an array of LEDs. Every minute, the Python program reads the light schedule (generated by MoonShineR: schedulers) to refresh the LED intensities. Users can run a moonlight schedule as well as a sunlight and twilight schedule simultaneously on the Raspberry Pi. In this way, the Raspberry Pi can separately control two arrays of LED strips, so as to fully re-create all three major sources of natural light, around the clock (see concept in Fig. 1).
Fig. 1 A flowchart of how MoonShineP works with the .csv schedule files created by MoonShineR to re-create light. MoonShineP can either create moonlight only (in a custom-made lightbox with neutral density filter sheets to calibrate light levels to natural moonlight levels), or sunlight and twilight (with the LEDs affixed to the ceiling, and no filtering utilized), or both moonlight and sunlight + twilight together.#
Table of contents#
Key to manual#
File names are indicated in pink text, for example
xxx.csv.File pathways names are indicated in italics, for example, Pi/Desktop/control_moon
Column names are also indicated in italics with single quote marks, for example, ‘datetime’.
R code, Python code, or terminal commands are shown in boxes. For example,
a line of code
Internal hyperlinks within this documents & links to external websites are indicated in blue text.