2. Software Notes - KPRoche/BLE-Beetle-Pixels GitHub Wiki
These Arduino sketches (programs) rely on the Adafruit_Neopixel library for simple control of the pixels, and the Arduino EEPROM library to access the non-volatile memory on the controller to store task information. Be sure to install the Neopixel libary in the libraries directory for your Arduino development environment (IDE). The EEPROM library is standard with the environment.
The BLE Beetle uses the same chipset as the Arduino Uno; set the Arduino compiler for Arduino Uno before compiling and uploading the sketch to your board.
The BLE Beetle is set up by default to run its BLE interface in parallel with its main serial interface, so the command parser in the code just monitors the serial port. There are two functions in these sketches that handle this.
-
bleRead() checks for available data at the serial port and reads bytes until it reaches a terminating character (semicolon, carriage return or line feed) (Semicolons are used by the Bluno Play app to terminate its transmissions). A programmable communications delay is used to make sure that characters are not lost due to timeouts. It then returns all those bytes as a String value. (Note -- that is the Arduino String type, not the lower-case string which is just a character array. The String variable type includes a whole bunch of built in functions.
-
processBLEcmd parses a string, searching for valid commands to execute. C++ cannot do a select function on a String, so the options are built as a set of cascaded, nested if and else if statements, which makes it easily extensible. It uses the String.indexOf() and String.substring methods extensively to search for keywords and values. You can feed a string to processBLEcmd; if one is not provided it will call bleRead() to get the next available string from the bluetooth interface.
The rest of the code consists of setting globals and the pixel class, plus setup(), loop(), and any light animation functions.
-
globals and the pixel class
- These set up the number of LEDs, the digital IO pin used for the LEDs, the timing constants for animations and the communications loop
- in addition, globals for setting the color and mode of the pixels are set.
- the series of LEDs is created (instantiated) as an instance of the NeoPixel class. They are named, assortedly, lights, or collar in the different sketchess.
-
setup()
- initializes the serial connection (Bluetooth and standard).
- reads the last used lighting mode from EEPROM into ScannerTask, increments it by one, and stores it back into EEPROM. (If the new task number is greater than the maximum allowed -- MaxTask -- it is reset back to 0 before being stored.)
- starts the light array
- sets all the LEDs to RGB 0,0,0 (off)
- sends the .show() command to the pixels to activate that off setting.
-
loop()
- checks for pending commands on the Bluetooth queue and implements them
- increments the color global if rainbow mode is active
- runs the illumination mode picked by ScannerTask
- waits a moment
- goes back to 1
-
Light Animation Routines
Depending on which sketch you are using, there are a number of functions for controlling the pixelsBLE_Simple_Neo
- Wheel is used to rotate the pixels around the color wheel in rainbow mode
- clearLEDs sets all LEDs to off. lights.show() must be called to activate the off.
- setColor sets all LEDs to a particular color and activates them
- colorFade sets all LEDs to a particular color, fading them up from off and then back down again
BLEetleBelt_V6 and BLEetleCollar
- theaterChaseRainbow does a theater-marquee style light chasing that fades in color from one end to the next
- theaterChaseColor does a theater-marquee chase in all one color
- multi_cylon does a "Larson" scanner back and forth in all one color
- multi_meteor does a meteor or raindrop effect in all one color
- split_meteor does a mirrored meteor pattern which either emanates from or flows into the center of the strip
- double_meteor does a mirrored meteor pattern crossing in both directions
- rainbow puts a rainbow on the strip from end to end and slowly moves it along the strip
- rainbowOrder used to build the rainbow progression for the two rainbow progressions
- finland a special version of meteor which has alternates white and blue patterns along the strip
- AllScans (currently commented out) rotates through several of the patterns in succession
One very nice feature of the BLE Beetle is that it is very easy to reprogram the Bluetooth name it broadcasts. Out of the box, it shows up as Bluno
To change the name of your beetle:
- Plug it into a usb port
- Fire up the Arduino IDE (programming environment)
- Under Tools, select Board > Arduino Genuino/Uno
- Under Tools, select Port > and pick the serial port corresponding to your Beetle
- Start the Serial Monitor (Ctrl-Shift-M)
- Set the controls in the bottom to No line ending and 115200 baud
- Type +++ in the bar at the top and click Send
- You should see Enter AT Mode in the window. This means you are now talking to the BLE chipset.
- Change the line end control to Both NL and CR
- Send the command AT+NAME=xxxxxxxxxxxxx where xxxxxxxxxxxxx is the name you want to give your device. You can use a maximum of 13 letters
- Send the command AT+NAME=? to read back the new name and make sure it is right.
- Send the command AT+RESTART to store the change and restart the chip.
- Close the Serial Monitor window, then restart it
- Your Beetle should now broadcast its new name!
A number of different BLE Terminal apps can be used to send mode and color change requests to the program. (DFRobot manufacturer of the BLE Beetle even publishes a free *Play Bluno" app which can talk to it.)
I had good luck with the BLE Terminal HM-10 iOs App, because it lets you assign commands to buttons, and you can set up to 25 different buttons. The free version is fully functional but shows ads, I found the $1.99 to eliminate the ads money well spent. When you fire up the app, you will see a list of nearby BLE devices:
select your device from the list displayed and the app will attempt to connect to it. Wait until the grey DFB2 button turns blue.
Once connected, the terminal must be put in DFB1 Mode (no echo) to work properly. Click on the blue DFB2 button and scroll all the way down. You will see DFB1 listed second from the end. click on it to set the mode.
Terminal is ready to go. You can set the number of buttons by clicking on the 3-dot menu symbol in the top right corner (also where you can access the "pay to eliminate ads" option).
To program a preset button, press and hold it, and the edit button will open. Here are a couple examples of doing so.
The free PLAY Bluno app from DFRobot includes a color picker, which is handy when playing with possible LED colors. Commands sent from the app end in a semicolon (;). The bleRead function is written to recognize commands that end in semicolons, and the processBLEcmd function will recognize the RGB color picker commands from this app.
The PLAY Bluno app sends a continuous stream of other strings to the Beetle, which can overwhelm these sketches. The simpler send-a-string terminals like the BLE Terminal HM-10 mentioned above should give a more responsive experience.
What commands can be sent from the app to the BLE Beetle depend on which of the sketches you are using; they are documented in the comments at the beginning of the code, also duplicated here for reference:
COMMANDS:
Mode commands change the animation pattern
MODE:PULSE a fade-up/fade-down effect across all LEDs
MODE:ON turn them on continously `
Color commands do not change the animation, but change the color used by them.
color commands will deactivate the rainbow mode.
<RGBLED>r,g,b; set the LED global color via the color picker in the play bluno app
RGB:r,g,b set the strip global color to an RGB value#
it is easier to use some presets
COLOR:WHITE set the whole strip white
COLOR:IN set the whole strip to indigo (always looks purple to me, while violet looks pink)
COLOR:BL set the whole strip to blue
COLOR:GR set the whole strip to green
COLOR:YL set the whole strip to yellow
COLOR:OG set the whole strip to orange
COLOR:RD set the whole strip to red
BRIGHT:nnn set the pixels to brightness nnn (0-255). NOTE this may change the hue.
Rainbow commands trigger a color progression while the pattern runs
RAINBOW:1 activate the rainbow modes
RAINBOW:0 deactivate the rainbow modes. (Has no effect on rainbow fade or chase if active)
Sleep command: used to use the low power library, but that requires a reset or interrupt to wake back up
SLEEP set the whole strip off, but leave the program running`
COMMANDS:
Mode commands change the animation pattern
MODE:RBFADE sets the strip to a continuous end-to-end rainbow fade
MODE:CYLON a multi-spot "Larsen Scanner" that goes back and forth
MODE:METEOR a multi-spot "raindrop" effect that goes in one direction
MODE:THEATER a classic theater marquee chase effect
MODE:PULSE a fade-up/fade-down effect across the whole strip
MODE:SPLIT a mirrored meteor effect that either emits from or meets in the center of the strip
(successive commands reverse the direction)
MODE:DB double meteor effect flying in both directions simultaneously
MODE:HC a cylon effect that alternates between blue and white along the whole strip
MODE:HM a meteor effect that alternates between blue and white along the whole strip
MODE:FL a meteor effect that has alternate blue and white meteors at the same time
Color commands do not change the animation, but change the color used by them.
color commands will deactivate the rainbow mode.
RGB:r,g,b set the strip global color to an RGB value#
it is easier to use some presets
COLOR:WHITE set the whole strip white
COLOR:IN set the whole strip to indigo (always looks purple to me, while violet looks pink)
COLOR:BL set the whole strip to blue
COLOR:GR set the whole strip to green
COLOR:YL set the whole strip to yellow
COLOR:OG set the whole strip to orange
COLOR:RD set the whole strip to red
Rainbow commands trigger a color progression while the pattern runs
RAINBOW:1 activate the rainbow modes
RAINBOW:0 deactivate the rainbow modes. (Has no effect on rainbow fade or chase if active)
Sleep command: used to use the low power library, but that requires a reset or interrupt to wake back up
SLEEP set the whole strip off, but leave the program running
Configuration commands let you experiment with some of the control parameters without recompiling.
E#nnnn change the number of "eyes" for meteors and cylons from the default of 6
S#nnnn change the number of eyes in the split meteor pattern from the default of 4
Split eyes must be in multiples of 2. If an odd number is supplied it will be incremented by 1
C#nn change the comm delay from the default of 5ms to nn ms
D#nn change the pattern timing delay from the default of 20 ms to nn ms`
The sketch automatically increments the task it is running (which animation mode is active) each time the controller is booted. If for some reason you cannot access the BLE Beetle via Bluetooth, you can scroll through the modes by rebooting or hitting the reset button.
This will not activate the SLEEP mode, as it is deliberately kept out of the automatic rotation, nor will it let you change the single color (the system defaults to blue, because it's one of my favorite colors). It will, however, hit both of the rainbow fading modes (the end to end rainbow fade, and the rainbow-fading theater chase).