.. highlight:: csharp

NeoPixel
========
NeoPixels are `Adafruit's brand <https://learn.adafruit.com/adafruit-neopixel-uberguide/overview#important-things-to-know-about-neopixels-in-general>`_ 
of LED strips that can be individually controlled.  The MetaWear firmware can communicate with up to 3 strands on the WS2811 protocol with the 
`INeoPixel <http://mbientlab.com/docs/metawear/csharp/1/interfaceMbientLab_1_1MetaWear_1_1Peripheral_1_1INeoPixel.html>`_ interface.

::

    using MbientLab.MetaWear.Peripheral;

    INeoPixel neopixel = metawear.GetModule<INeoPixel>();

Initializing a Strand
---------------------
Before we can interact with a NeoPixel strand, we first need to initialize memory on the MetaWear board to store NeoPixel information. To initialize the 
strand, call the 
`InitializeStrand <http://mbientlab.com/docs/metawear/csharp/1/interfaceMbientLab_1_1MetaWear_1_1Peripheral_1_1INeoPixel.html#a0ac56072fa70fce07aa3239d25f5172a>`_ method.  
When calling the function, you will need to take into consideration these parameters:

* Operating frequency (either 800 Hz or 400 Hz)  
* How many LEDs to use  
* What color ordering the strand requires (RGB, GRB, etc.)  
* Which gpio pin the data wire is connected to  

::

    using MbientLab.MetaWear.Peripheral.NeoPixel;

    // initialize memory for a strand #2 that operates at 800KHz (fast), has 60 leds, 
    // uses rbg color order, and has a data wire connected to gpio pin 1
    IStrand strand = neopixel.InitializeStrand(2, ColorOrdering.WS2811_RBG, StrandSpeed.Fast, 1, 60);

The function returns an `IStrand <http://mbientlab.com/docs/metawear/csharp/1/interfaceMbientLab_1_1MetaWear_1_1Peripheral_1_1NeoPixel_1_1IStrand.html>`_ object and can be 
retrieved at a later time by calling 
`LookupStrand <http://mbientlab.com/docs/metawear/csharp/1/interfaceMbientLab_1_1MetaWear_1_1Peripheral_1_1INeoPixel.html#a0b16ecd7099207fd3d52144f7926d1b0>`_ with the same strand 
number used for `InitializeStrand`.

::

    strand = neopixel.LookupStrand(2);

Setting Colors
--------------
When you have received your strand object, you can start turning on the LEDs using 
`SetRgb <http://mbientlab.com/docs/metawear/csharp/1/interfaceMbientLab_1_1MetaWear_1_1Peripheral_1_1NeoPixel_1_1IStrand.html#afc0f4393321e84233b727145b655292e>`_.  Any changes 
to the led state will immediately be propogated to the strand unless a hold is enabled with the  
`Hold <http://mbientlab.com/docs/metawear/csharp/1/interfaceMbientLab_1_1MetaWear_1_1Peripheral_1_1NeoPixel_1_1IStrand.html#a1ee69bd4928670e4bf2b419ece7b23db>`_ function.  When 
`Release <http://mbientlab.com/docs/metawear/csharp/1/interfaceMbientLab_1_1MetaWear_1_1Peripheral_1_1NeoPixel_1_1IStrand.html#a56d471bb8a31a87809c30609539d202b>`_ is called, all the LED changes 
will appear simultaneously.

::

    // Enable hold to lock the strand state
    strand.Hold();

    strand.SetRgb(0, 255, 0, 0);
    strand.SetRgb(1, 0, 255, 0);
    strand.SetRgb(2, 0, 0, 255);

    // Disable hold, which will now update the strand with any state changes
    strand.Release();

Pattern Rotation
----------------
Once you have a color pattern on your strand, you can rotate the pattern using 
`Rotate <http://mbientlab.com/docs/metawear/csharp/1/interfaceMbientLab_1_1MetaWear_1_1Peripheral_1_1NeoPixel_1_1IStrand.html#a41ce01eb035cfe3dee135361632fe6b9>`_.  
By default, the pattern will rotate indefinetly however you can set a limit by setting the ``repetitions`` parameter.  

If an indefinite rotation has started, call `StopRotation <http://mbientlab.com/docs/metawear/csharp/1/interfaceMbientLab_1_1MetaWear_1_1Peripheral_1_1NeoPixel_1_1IStrand.html#a23af9060381d56bb12bb10e46885b572>`_ to manually 
terminate the rotation.  ::

    using MbientLab.MetaWear.Peripheral.NeoPixel;

    // Rotate pattern 16 times, moving away from the board with a delay of 500ms
    strand.Rotate(RotationDirection.Away, 500, repetitions: 16);
     
    // Rotate pattern indefinitely, moving towards the board with a delay of 250ms
    strand.Rotate(RotationDirection.Towards, 250);
     
    // Stop pattern rotation
    strand.StopRotation();

Clean Up
--------
When you are down using your NeoPixel strand, make sure you turn off the LEDs and deallocate the memory used for that particular strand.  You can discard 
the ``IStrand`` object after calling `Free <http://mbientlab.com/docs/metawear/csharp/1/interfaceMbientLab_1_1MetaWear_1_1Peripheral_1_1NeoPixel_1_1IStrand.html#a16a1a6d9e753debd2b51d59c2262eb46>`_.

::

    // turn off leds from index [0, 59] (60 leds)
    strand.Clear(0, 59);

    // free
    strand.Free();