Advanced Configuration

We have provided lots of ways to reconfigure the software depending on the options you've chosen when building this project and we have provided lots of ways to set various defaults. You may also need to calibrate the photocell to set the threshold for what is considered "day" or "night". You may also need to calibrate the touch controls because depending on the size or type of screw you have used, the length of the wires, the method used to connect them it can vary the capacitance of that system. If you want to use the infrared controls using your own remote control rather than the recommended Adafruit Mini Remote you will need to configure that as well. 

We have already told you how to turn off and on various features of this project such as the touch controls, IR sensor, photocell etc. in this section "Sample Code and Audio Files". Here are the remaining configuration changes you can make.

Defining the Top Pixel

If you happen to mount your NeoPixel ring or the faceplate at a slight angle, you may not end up with the "0" pixel exactly at the top. On line 73 of the main sketch tab you can modify the following line to change the top pixel.

Download: file
//fudge factor in case you don't get your pixel ring oriented properly
#define TOP_PIXEL 0

Calibrating Touch Controls

The touch controls work by measuring the electrical capacitance of the wires connected to pins A0 through A3. It uses the Adafruit_FreeTouch library. Normally there will be a low capacitance read from those pins and when you touch them with your finger you will get a higher reading. You have to set a threshold which defines when the pin has been touched. These values can vary even from pin to pin in your project. It depends on the length of the wires, how they are routed past other components, the types of screws to which you have attached the wires, and how you attached them. To calibrate this system, there is a sample sketch called "freetouch_test" included in your package of programs. You should open your serial monitor and upload this sketch. It will print out 4 values showing the current readings five times per second. You might also want to try opening the plotter function of the Arduino IDE to get a graphical representation of the data as you touch each of the pins.

As you can see from the graph, there is a wide variety for the upper and lower values of each of the four buttons. We will have to pick different threshold values for each one. Once you have an idea of a good threshold that accurately describes when you have touched the pins, you can modify the values in the original "clock" sketch at approximately line 94. 

Download: file
#if(USE_TOUCH)
  #include "Adafruit_FreeTouch.h"
  #define TOUCH_SETUP_THRESHOLD 650
  #define TOUCH_RIGHT_THRESHOLD 550
  #define TOUCH_UP_THRESHOLD    550
  #define TOUCH_DOWN_THRESHOLD  750

Additional configuration changes you may need to make begin on line 32. We have defined which pin numbers correspond to the various touch controls. If you have wired up your controls in a different order than we have, you might need to change these pin numbers.

Download: file
#define TOUCH_SETUP_PIN   A3
#define TOUCH_RIGHT_PIN   A2
#define TOUCH_UP_PIN      A1
#define TOUCH_DOWN_PIN    A0 

Initial Defaults

Beginning at line 38 there are series of defines that are the values used in the menu system and other startup values. The first few lines define the various modes used for animation, audio settings, chimes etc. The following lines can be edited to set up the default values when the clock is first powered up. Once you've played around with the various features of the clock, you will probably want to change these defaults to the values you prefer and then recompile and upload so you don't have to change all of these values each time the clock is powered up.

Download: file
//Audio, Music and Animation modes
#define MODE_OFF      0
#define MODE_ON       1
#define MODE_TIMED    2
#define MODE_LIGHT    3
#define MODE_RANDOM   4
#define MODE_WESTMIN  5
#define MODE_CUCKOO   6

//Initial default settings. These values are set in "audio_menu.h" and other places
// but the defaults are defined here for easy access.
#define AUDIO_DEFAULT       MODE_TIMED
#define ANIMATION_DEFAULT   MODE_RANDOM
#define MUSIC_DEFAULT       MODE_RANDOM
#define CHIMES_DEFAULT      MODE_WESTMIN
#define BRIGHT_MODE_DEFAULT MODE_ON
#define VOICE_DEFAULT       true
#define QUARTERLY_DEFAULT   true
#define HOURLY_DEFAULT      true
#define MARKS_DEFAULT       true
#define ALARM_DEFAULT       true
#define ALARM_HOUR           7
#define ALARM_MINUTES       30
#define DAYTIME_START_DEFAULT   10
#define NIGHT_BEGINS_DEFAULT    22
#define VOLUME_DAY_DEFAULT      20
#define VOLUME_NIGHT_DEFAULT    40
#define VOLUME_THRESHOLD        50
#define BRIGHT_DAY_DEFAULT       6
#define BRIGHT_NIGHT_DEFAULT     2
#define HOURS_DEFAULT           12
#define MINUTES_DEFAULT          0
#define LIGHT_THRESHOLD        100

Changing IR Codes

The infrared receiver uses IRLib2 to receive and decode infrared signals. This powerful open source library supports 11 different popular IR protocols and a variety of variations of those 11 protocols. We've already configured it for the Adafruit Mini Remote which uses the popular NEC protocol. However you can use any remote want if it uses a protocol that is supported by IRLib. Obviously you don't want to pick a remote protocol that is going to interfere with any consumer electronic devices you have. Otherwise every time you turn up the volume on your TV, the clock with change. Pick a device that will interfere. For example my clock is in my office but my Blu-ray player is in my living room. I could use the Blu-ray codes to set the clock. If you have universal remote, perhaps program one of the device sections for some device do not own. Any of the 11 protocols supported by IRLib2 should work however we recommend against using Sony protocol because it automatically sends three copies of every signal when you push the button. That might give you double or triple signals where you don't want them.

There is an extensive user's manual for IRLib2 available in the "libraries/IRLib2/manuals" folder of the library. It is available in Microsoft Word, PDF, and EPUB formats.

In the "clock" program at line 82 you will see the following section which sets up IRLib2 to use the NEC protocol and to define the codes for the Adafruit Mini Remote.

Download: file
#if(USE_IR)
  //set up IRLib2 to use NEC protocol and Adafruit mini-remote
  #include "IRLibRecvPCI.h"
  #include "IRLibDecodeBase.h"
  #include "IRLib_P01_NEC.h"
  #include "adafruit_mini_codes.h"
  IRrecvPCI myReceiver(IR_PIN); 
  IRdecodeNEC myDecoder;   
#endif

Temporarily comment out the three #include statements and add a new statement to include "IRLibAll.h". Also change the class type of the decoder from "IRdecodeNEC" to be just "IRdecode". This will enable IRLib2 to decode not just NEC protocol but all of the protocols it supports. The code should now look like this…

Download: file
#if(USE_IR)
  //set up IRLib2 to use NEC protocol and Adafruit mini-remote
  //#include "IRLibRecvPCI.h"
  //#include "IRLibDecodeBase.h"
  //#include "IRLib_P01_NEC.h"
  #include "adafruit_mini_codes.h"
  #include  "IRLibAll.h"
  IRrecvPCI myReceiver(IR_PIN); 
  IRdecode myDecoder;   
#endif

At approximately line 288 you will see a debugging section that includes a statement to dump details of the code received by IRLib2. You should uncomment this statement and also turn on debugging at the top of the sketch.

Download: file
/*
 * Talking Musical Neo-Pixel Clock with Infrared, BLE, and Touch Controls
 *    by Chris Young
 *  released to the public domain
 */
//Various options. Set to zero to disable or one to enable.
//Enables Serial Monitor Debugging
#define MY_DEBUG 1

//... Skip down to line 288

     #if (MY_DEBUG)
       myDecoder.dumpResults(false);
     #endif

Compile and upload the sketch with your serial monitor open. Try pressing various buttons on your remote control such as the arrow keys, set up button, play button, and some sort of reset or exit button to be used as the reset function of the clock. We tried using our Blu-ray remote control. We pressed the  up, down, left, right, menu, play, and exit buttons in that order. We get the following output on the serial monitor.

Download: file
Debug output ready.
System Initialized
Decoded Samsung36(8): Value:E18E7 Adrs:400 (36 bits) 
Decoded Samsung36(8): Value:E9867 Adrs:400 (36 bits) 
Decoded Samsung36(8): Value:ED827 Adrs:400 (36 bits) 
Decoded Samsung36(8): Value:E58A7 Adrs:400 (36 bits) 
Decoded Samsung36(8): Value:E6897 Adrs:400 (36 bits) 
Decoded Samsung36(8): Value:E28D7 Adrs:400 (36 bits) 
Decoded Samsung36(8): Value:ED42B Adrs:400 (36 bits) 

This tells that it successfully decoded Samsung36 protocol which is protocol number 8 in the IRLib2 system. It is a 36 bit protocol consisting of two parts. An Address of 0x400 which seems to be constant and a Value of a five digit hexadecimal number that changes depending upon the function. We can now plug in these values into the sketch beginning at approximately line 274 change the code to read as follows:

Download: file
  #if(USE_IR)
    if (myReceiver.getResults()) {//was a command received by IR?
      if (myDecoder.decode()){    //is that the right protocol?
        switch(myDecoder.value) {
          case 0xE18E7: Value= UP_ARROW; break; 
          case 0xE9867: Value= DOWN_ARROW; break; 
          case 0xED827: Value= LEFT_ARROW; break; 
          case 0xE58A7: Value= RIGHT_ARROW; break; 
          case 0xE6897: Value= SETUP; break; 
          case 0xE28D7: Value= PLAY; break; 
          case 0xED42B: Value= RESET; break; 
        }
     }
     #if (MY_DEBUG)
       myDecoder.dumpResults(false);
     #endif
     myReceiver.enableIRIn(); 
    }
  #endif

Once you have verified that everything is working, you can comment out the "myDecoder.dumpResults(false);" line above and turn off debugging at the top of the sketch. Currently we have IRLib2 configured to receive all protocols which is quite wasteful, now that we know that we use protocol 8 which is "Samsung36" we can modify IRLib include files to use just that protocol. Change line 83 and beyond to read as follows...

Download: file
#if(USE_IR)
  //set up IRLib2 to use NEC protocol and Adafruit mini-remote
  #include "IRLibRecvPCI.h"
  #include "IRLibDecodeBase.h"
  #include "IRLib_P08_Samsung36.h"
  IRrecvPCI myReceiver(IR_PIN); 
  IRdecodeSamsung36 myDecoder;   
#endif

This code looks very much like the original version except that we have substituted "IRLib_P08_Samsung36.h" in place of the previous include file for the NEC protocol. We have also modified the decoder so that it uses the "IRdecodeSamsung36" class. We have also removed the reference to "adafruit_mini_codes.h" which we are no longer using.

If your remote is not using one of the protocols supported by IRLib2 there is one other alternative. There is a hash code decoder available that will attempt to generate a unique hash code based on your button presses. It will attempt to generate a unique 32-bit hex value based on your button press. This is not as accurate or efficient as using the actual protocol but it will work in a pinch. To use the hash decoder, change the include section at line 83 to read as follows:

Download: file
#if(USE_IR)
  //set up IRLib2 to use NEC protocol and Adafruit mini-remote
  #include "IRLibRecvPCI.h"
  #include "IRLibDecodeBase.h"
  #include "IRLib_HashRaw.h"
  #include "adafruit_mini_codes.h"
  IRrecvPCI myReceiver(IR_PIN); 
  IRdecodeHash myDecoder;   
#endif

Then try pushing buttons on a remote, recording the 32-bit hex values and substituting them into appropriate portion of the sketch as we did before.

Calibrating the Photocell

If you're using a light-based option to define day and night for the audio volume or NeoPixel brightness level you may need to change the threshold value that determines what given amount of ambient in the room constitutes "night".

There is a sample sketch included with the package titled "photo_test" which will allow you to verify that the photocell is working. Upload the sketch and open the serial monitor. Cover or uncover the photocell and watch the values change. Once you know it is working you can use the "clock" sketch with debugging turned on to collect data on ambient light values in your room overnight.

You should turn on debugging at the top of the sketch and open the serial monitor and upload. The sketch will print out the amount of light received by the photocell every 15 minutes. Leave it running overnight and then look at the results next day. This should help you determine an appropriate threshold level for your environment. Here are the results from an overnight run in my home office.

Download: file
Photocell value:535	The current time is 9:15 p.m.
Photocell value:536	The current time is 9:30 p.m. <-Office lights off
Photocell value:60	The current time is 9:45 p.m.
Photocell value:62	The current time is 10 p.m.
Photocell value:61	The current time is 10:15 p.m.
Photocell value:63	The current time is 10:30 p.m.
Photocell value:64	The current time is 10:45 p.m.
Photocell value:61	The current time is 11 p.m.
Photocell value:64	The current time is 11:15 p.m.
Photocell value:63	The current time is 11:30 p.m.
Photocell value:61	The current time is 11:45 p.m.
Photocell value:62	The current time is 12 midnight <-House lights off
Photocell value:9	The current time is 12:15 a.m.
Photocell value:10	The current time is 12:30 a.m.
Photocell value:9	The current time is 12:45 a.m.
Photocell value:9	The current time is 1 a.m.
--- Skipping ahead--
Photocell value:9	The current time is 2:15 a.m.
Photocell value:23	The current time is 2:30 a.m. <-Late-night bathroom visit
Photocell value:0	The current time is 2 a.m.
Photocell value:9	The current time is 2:15 a.m.
--- Skipping ahead--
Photocell value:9	The current time is 6:30 a.m.
Photocell value:12	The current time is 6:45 a.m.
Photocell value:11	The current time is 7 a.m.
Photocell value:27	The current time is 7:15 a.m.
Photocell value:46	The current time is 7:30 a.m.<-Daylight begins
ALARM!
Photocell value:31	The current time is 7:45 a.m.
Photocell value:47	The current time is 8 a.m.
Photocell value:43	The current time is 8:15 a.m.
Photocell value:47	The current time is 8:30 a.m.
Photocell value:69	The current time is 8:45 a.m.
Photocell value:68	The current time is 9 a.m.
Photocell value:60	The current time is 9:15 a.m.
Photocell value:75	The current time is 9:30 a.m.
Photocell value:77	The current time is 9:45 a.m.
Photocell value:76	The current time is 10 a.m.
Photocell value:85	The current time is 10:15 a.m.
Photocell value:82	The current time is 10:30 a.m.
Photocell value:114	The current time is 10:45 a.m.
Photocell value:543	The current time is 11 a.m.   <-Turned on lights
Photocell value:541	The current time is 11:15 a.m.
Photocell value:552	The current time is 11:30 a.m.

Based on this information we set the light threshold at 100 which can be found outline 70 of the clock sketch.

Download: file
#define LIGHT_THRESHOLD        100
This guide was first published on Jul 30, 2018. It was last updated on Jul 30, 2018. This page (Advanced Configuration) was last updated on Aug 05, 2019.