Build a Luminosity Module With AtHome

AtHome is a fully opensource and openhardware student project made by the group AtHome from Epitech, aiming to develop a connected solution of several individual sensor modules communicating with a self-hosted database exposing an API used to feed a smartphone application and a web application. The modules monitor the indoor environment of a house and are able to give a visual feedback to the user, going from green (good) to red (bad) and the transmitted data are visible by the user through the serial communication of a module or on our applications if you use them.

Even though this project is still under an active development, the basic functionalities of our modules are now ready and supposedly easy to use to develop custom modules. So, that's why I'm proposing you to see how to build your own simple module with this example of luminosity module.

These modules are basically built with an Arduino-compatible board (a partial Arduino core should be enough as long as it have Stream, Wire and a UART stream support), a LED (red one or RGB) turning red in case of issue, a sensor, a power supply (wall power-supply or battery) and a laser-cut case.

Yes, it’s definitely not new, there are lot of sensor projects but we hope other features such as health issues detection, communication and storage of information on a self-hosted server and visualization application would help you. Or if you just want to monitor your house, simple projects or no less interesting :)

For this project, you'll need a few components to build your AtHome module:

• 1x Arduino-Compatible board: Here I'll use an Arduino UNO (but it also works with other boards such as TI Launchpads and ESP8266 boards)
• 1x sensor: I'll use a TSL2561 luminosity sensor (the list of supported sensors is available on the documentation of our library)
• 1x led: I'll use a Grove Chainable RGB LED here (but it can also be a simple red led or a NeoPixel)
• Dupont Wires

The list of compatible components is available on the documentation of our project.

To install our library, you'll need to download from our repository (we'll publish it later on the Arduino IDE list and PlatformIO) with this link:

https://gitlab.com/Woodbox/Framework/-/jobs/artifacts/master/download?job=deploy

Then, go in the Arduino IDE and choose "Sketch > Include Library > Add .ZIP Library...". Then select the zip file named "artifacts.zip" and click on "OK".

To work, our library need some others libraries to be installed on your computer:

• Arkhipenko TaskScheduler library
• SEEED Studio Grove Digital Light Sensor library
• SEEED Studio Grove Chainable RGB LED library
• Adafruit NeoPixel library

You can install them through the library manager of the Arduino IDE, by going on "Sketch" > "Include Library" > "Manage libraries...".

In the new window that will open, write in the white search bar the name of the library you want to install, then click on its block. An "Install" button will appear, you just need to click on it and the IDE will download it and install it for you.

We’ll begin with the sensor. Connect through a wire the VCC pin of the TSL2561 to the 5V pin of the Arduino, the GND pin of the sensor to one of the GND pin of the Arduino and the SDA and SCL pins of the sensor to SDA and SCL pins of the Arduino. Now you’re done!

Now, connect the VCC pin of the Grove Chainable RGB LED to the 5V pin of the Arduino and the GND pin of the LED to the second GND of the Arduino. If you're Arduino as only one 5V pin, you can use a breadboard to connect the 5v of the Arduino to a + row of the breadboard and connecting all your components 5V pins on it, or soldering them together on a piece of stripboard or use wago connectors or whatever you prefer. Now, connect the CI pin of your LED to the pin 7 of your Arduino and the DI pin of your LED to the pin 8 of your Arduino. If you don't have such an LED, don't worry, it's possible to use the built-in LED of your Arduino board or a classic one with just a small change in the code.

Let's create a new sketch and write the code for our module.

If you're not interested by the explanation of the sketch, you can just copy and paste it in your Arduino IDE:

#include <AtHome.h>

using LightModule = AtHomeModule<uint16_t, 1>;
Stream *streams[] = {&Serial, nullptr};
GroveChainableLED::Pins grovePins = {7, 8};
GroveChainableLED led(&grovePins);
LightModule *module = LightModule::getInstance();

void setup() {
  // put your setup code here, to run once:
  Serial.begin(9600);
  module->setStreams(streams);
  GroveDigitalLightSensor *lightSensor = new GroveDigitalLightSensor();
  module->setSensor(lightSensor);
  module->setDisplay(&led);
  module->setup();
}

void loop() {
  // put your main code here, to run repeatedly:
  module->run();
}

If you want to understand all what this code is doing, you can read the following or if you're not interested, you can jump directly to the next step.

To begin, we need to include our library in our sketch by writing this line at the top of the sketch:

#include <AtHome.h>

Now, we need to create an alias to the module object we will use. You can see it as a box with several buttons used to change it's components, start it, stop it, ...etc. As it's a box built by a template (like usual template we use for projects as humans, it has a starter base and the compiler of Arduino build the final code based on parameters we give to him) defining the type representing a sensor value and the number of sensor values we want to hold in memory, it's specified in it's name and should normally be repeated every time we want to use it. Which is a bit annoying, that's why we'll associate a new name, an alias, to the full name of this box.

Let's say for example I want this box to be named "LightModule", as it will be used to implement a luminosity monitoring module and I want to keep only 1 value at a time. The luminosity is represented in lux as an integral type by our TSL2561 sensor, which is represented as a uint16_t by computers. Our alias will look like this:

using LightModule = AtHomeModule<uint16_t, 1>;

the "using" keyword means we're creating an alias and the name we give it just after corresponds to the sequence after the "=" character.

"AtHomeModule" is the real name of this box we're giving a new name, and the parameters defining the value representation and the number of values kept in memory is listed between "<" and ">".

Now, when we'll use later the name "AtHomeModule", Arduino will know it refers to the full name "AtHomeModule".

If you want your box to be able to keep 5 values in memory instead of 1, you just need to replace the "1" by "5" and Arduino will generate for you a different type of box able to do what you want. Note, however, that if the module is programmed to send its values before it has the time to effectively measure 5 values of the sensor, you'll never see 5 of them being sent as it sends only the new values since the last upload.

Next, we need to create an array of pointers containing pointers on Arduino streams used by the module to communicate, always terminated by the keyworkd "nullptr". Here, I'm using only the "Serial" stream of the Arduino which communicate with the computer by the USB port, so the array looks like this:

Stream *streams[] = {&Serial, nullptr};

The "*" character means the type is a pointer (the location of the element, not the element itself) and the "[]" brackets means in Arduino it's an array, so we can put multiple values.

Next, we need to create our LED. To do this, we need to write the following two lines;

GroveChainableLED::Pins grovePins = {7, 8};
GroveChainableLED led(&grovePins);

If you don't have a Grove RGB LED but still want a visual feedback, you can do it with a simple change in the sketch. Replace the two previous lines by this line:

MonochromaticLED led(LED_BUILTIN);

In this configuration the green built-in LED will turn on as long as the monitored value is ok for health and turn off when it's out of bond. If you prefer to have it turning on when it's out of bond (because you're using for example a red LED instead of the green one on pin 13) you can use this line instead:

MonochromaticLED led(LED_BUILTIN, true);

The next step is to create our module itself. It's done the first time we get it's location in memory by calling the "getInstance" method, like this:

LightModule *module = LightModule::getInstance();

Then, we need to set the parameters in the "setup()" function of Arduino, beginning by initializing the "Serial" port as usual in Arduino sketches:

Serial.begin(9600);

We create the light sensor by writing this line:

GroveDigitalLightSensor *lightSensor = new GroveDigitalLightSensor();

Then, we tell our module to use our array of pointers on Arduino Stream to communicate through them:

module->setStreams(streams);

We also tell our module to use our light sensor to monitor the light intensity where the module is:

module->setSensor(lightSensor);

We tell our module to use our LED to give us a visual feedback:

module->setDisplay(&led);

Finally, we tell our module it's ready to do any internal configuration it needs to do by calling its own "setup" function:

module->setup();

Our last step is now to call the "run()" function of our module, which is designed to be called at each iteration of the "loop" function of Arduino by writing this line inside the "loop" function:

module->run();

Now, our sketch is finally ready to upload to the Arduino and test our module!

To upload the sketch to the Arduino, choose your Arduino UNO board by going in "Tools" > "Port" > "[COMx or /dev/x] (Arduino/Genuino UNO)".

Last thing, just click on the "Upload" button (the circle button with an arrow pointing to the right, the second icon of the tool bar) to upload the sketch in your board.

It's done! Now you're module should be working and sending values to your computer visible in the Serial Monitor of Arduino. You can check it by opening the "Serial Monitor" of Arduino in the "Tools" menu and you should have an output looking like the second title picture of this step :)

You can build a simple box case for your module by laser cutting it in a 3mm plywood plank.

To make our box cases, we use makercase to prepare a template at the desired dimensions that we customize later. You'll find the svg file of the luminosity module attached to this step.

Then just glue the faces together excepting one so you can open it later, put your circuit inside and stick the LED in the hole of the case (we use transparent tape to fill the hole and diffuse the light in addition to stick the LED in front of it).

Now just add a battery to power your Arduino, close the case and your module is ready and should be looking good :)