effect location and general guidelines

• effects can be found in the fx folder, which is used by both src and src-heart builds.
  • you MUST add a version of your effect that will run on the heart badges using #ifndef MASTER_BADGE - see existing effects to understand what to do.
  • please name your effect file starting with fx-
  • for the effect name to be displayed in the master badge UI - keep it as short/simple as possible.
• please make helpful comments explaining the design of your effect at the top
• the alphabetically first effect will be the default effect upon start (unless it is a temporary effect, which cannot be the first effect)

how are effects run?

a note about brightness

• The methods that set the LEDs all contain a int8 parameter called 'shift' that is used to dim the brightness of the LEDs - it does so by doing a right bitshift >> (x >> n is like doing x/(2^n)) on the LED color values.
• shift is set to 2 by default, which means the brightness is set to 25% of full brightness.
• do not hardcode the shift value when setting LED colors in your effects - brightness needs to be modified globally during times like charging, change in ambient lighting, etc.

color

• There are two ways you can think about color - RGB or HSV (hue, saturation, value(brightness)).
• The LEDs need RBG values, but HSV values seem to provided a more pleasing (less harsh, RGBy) experience.
• It's advisable to do your colors in HSV, and then convert to RGB.
  • There are handy conversion functions HsvToRgb(HsvColor hsv) and RgbToHsv(RgbColor rgb) to help you with this.
• a set of HSV colors is provided to you - it is recommended to use these colors. (so that their properties can be easily modified at run time by the master)
  • the number of hues is numOfBaseHsvColors and it is modifiable by a shell command within the fx commands
    • there are also settings for the saturation and brightness of these base HSV colors that can be also modified via shell command.
  • to get a struct HsvColor call the function getBaseHsvColor(uint8_t index) passing in the (1 based) index of the color you'd like out of the max of numOfBaseHsvColors.

accessing sensor data

accelerometer

current accel values in x, y, and z directions

• these values are provided by the IMU (does gyro and accel)
• to get accelerometer values:
  • #include "gyro.h" at the top of your file if it isn't there already.
  • use the struct accel_data as the variable type you'll populate with accel data: struct accel_data data;
  • then call this function to populate the xyz accel values: gyro_Get_X_Axes(&data);
    • X in this case stands for accelerometer!
  • data.x, data.y, and data.z contain values in G * 1000.

freefall detection

• this is also detected by the IMU, so you must #include "gyro.h"
• this is already included in led.h, there is an int variable called 'bumped' that gets set to 1 whenever freefall is detected.
  • after doing if(bumped) don't forget to reset bumped = 0 at some point.

temperature

• temperature readings are also done by the barometer thread in main.c (same sensor does barometer and temp)
• baro_temp is the float value you can access for your effects

microphone

barometer

• barometer readings are done by a thread in main.c (reading this on your own will cause undue work on the processor!)
  • baro_avg is the value in mPa obtained by averaging BARO_HISTORY number of readings
    • if you are using baro_avg you must also check that baro_avg_valid == 1. This means that the full number of readings have been taken (this will take a little bit after startup).
  • when the next reading is BARO_CHANGE_SENSITIVITY (in mPa) outside of baro_avg, pressureChanged() is called in the led file.
• the static variable pressure_changed in led.c will be set to 1. This is what you use to determine if pressure changed abruptly!
  • you must reset this value to 0 yourself.

gyro

single tap detection

• single tap (or smack?) of the cube will trigger an event that calls the method singletap() in led.c.
  • This will then set the static variable singletapped in led.c to 1. This is what you use to determine if someone smacked the cube once.
    • you must reset this value to 0 yourself.
• tap (both single and double tap) has a sensitivity setting, it is LSM6DS3_TAP_THRESHOLD_MID_LOW by default.

paging from badges

There is a command line option to let you simulate a page - type 'page'

When you page, it raises a radio_page event, which is handled by method handle_radio_page in orchard-app.c

handle_radio_page:

• sets the effect to be used during paging (it uses the name of the effect, not the method name)
• calls radioPagePopup in paging.c
  • this used to do some UI stuff but it doesn't any more now that the UI is gone
  • it sleeps for PAGE_DISPLAY_MS, which is currently set to 3500ms. During this time the page effect will be running.
• sets everything back to the previous lighting effect.

troubleshooting tips

If you want to print to the console, you do it like this:

• chprintf(stream, "%f\n\r", floating_point_number);
• chprintf(stream, "%d\n\r", decimal_number);
• chprintf(stream, "%s\n\r", string_thing);