.. highlight:: java

Settings
========
Developers can use the `Settings <https://mbientlab.com/docs/metawear/android/3/com/mbientlab/metawear/module/Settings.html>`_ module to configure ble 
pereferences and retrieve general board information.  You can combine preference changes with the :doc:`macro` module to make them permanent.

::

    import com.mbientlab.metawear.module.Settings;

    final Settings settings = board.getModule(Settings.class);

Ble Advertising
---------------
Advertising parameters control how the Bluetooth LE radio sends its adversiting packets and are configured with the 
`BleAdvertisementConfigEditor <https://mbientlab.com/docs/metawear/android/3/com/mbientlab/metawear/module/Settings.BleAdvertisementConfigEditor.html>`_ 
interface.  You can configure paramters such as the device name, timeout, tx power, and scan response.

::

    import com.mbientlab.metawear.module.Settings;
    
    settings.editBleAdConfig()
            .deviceName("AntiWare")
            .txPower((byte) -4)
            .interval((short) 1024)
            .timeout((byte) 100)
            .commit();

Check out these posts from the Nordic Developer Zone if you are unsure of what these parameters do:  

* https://devzone.nordicsemi.com/question/53348/advertising-interval-and-advertising-timeout/?answer=53385#post-id-53385  
* https://devzone.nordicsemi.com/question/39731/range-of-values-for-tx-power/?answer=39733#post-id-39733  
    
Connection Parameters
---------------------

Bluetooth LE connection parameters control how the ble devices communicate with each other.  Configuring thes parameters is done with the 
`BleConnectionParameterEditor <https://mbientlab.com/docs/metawear/android/3/com/mbientlab/metawear/module/Settings.BleConnectionParametersEditor.html>`_ 
interface.  A more detailed explanation on connection parameters can be found on the Nordic Developer Zone:  

* https://devzone.nordicsemi.com/question/60/what-is-connection-parameters/  

::

    // change min conn interval to 10ms, 
    // max conn interval to 1024ms
    settings.editBleConnParams()
            .minConnectionInterval(100f)
            .maxConnectionInterval(1024f)
            .commit();

Battery State
-------------
Battery state is defined as a forced data producer and represented by the 
`BatteryState <https://mbientlab.com/docs/metawear/android/3/com/mbientlab/metawear/module/Settings.BatteryState.html>`_ class.  Unlike reading the 
battery characteristc with the ``MetaWearBoard`` class, reading the battery state with the ``Settings`` module lets you use the battery data with the 
route API.

::

    settings.battery().addRouteAsync(new RouteBuilder() {
        @Override
        public void configure(RouteComponent source) {
            source.stream(new Subscriber() {
                @Override
                public void apply(Data data, Object ... env) {
                    Log.i("MainActivity", "battery state = " + data.value(BatteryState.class));
                }
            });
        }
    }).continueWith(new Continuation<Route, Void>() {
        @Override
        public Void then(Task<Route> task) throws Exception {
            settings.battery().read();
            return null;
        }
    });

Handling Disconnects
--------------------
The board can be programmed to react to a disconnect by registering an 
`Observer <https://mbientlab.com/docs/metawear/android/3/com/mbientlab/metawear/Observer.html>`_ with the 
`onDisconnectAsync <https://mbientlab.com/docs/metawear/android/3/com/mbientlab/metawear/module/Settings.html#onDisconnectAsync-com.mbientlab.metawear.CodeBlock->`_ function.

::

    final Led led = board.getModule(Led.class);

    settings.onDisconnectAsync(new CodeBlock() {
        @Override
        public void program() {
            led.editPattern(Color.RED, PatternPreset.SOLID)
                    .repeatCount((byte) 2)
                    .commit();
            led.play();
        }
    });


Power Status
------------
Firmware v1.3.2 exposes battery charging and power status notifications which provides information on when the battery is charging / not charging and 
when a power source is attached / removed, respectively.  The data is interpreted as a byte or boolean with 1 (true) signifying battery charging / 
power source attached, and 0 (false) meaning battery not charging / power source removed.  Not all boards support this feature and a null pointer will 
be returned if `powerStatus <https://mbientlab.com/documents/metawear/android/3/com/mbientlab/metawear/module/Settings.html#powerStatus-->`_ or 
`chargeStatus <https://mbientlab.com/documents/metawear/android/3/com/mbientlab/metawear/module/Settings.html#chargeStatus-->`_ is called on an 
unsupported board.

::

    settings.powerStatus().addRouteAsync(new RouteBuilder() {
        @Override
        public void configure(RouteComponent source) {
            source.stream(new Subscriber() {
                @Override
                public void apply(Data data, Object... env) {
                    Log.i("MainActivity", "power source state changed: " + data.value(Byte.class));
                }
            });
        }
    });

Because the power and charge statuses are active data producers, the module has provided the ``readCurrentChargeStatusAsync`` and 
``readCurrentPowerStatusAsync`` methods so your app can retrieve the current charge and power statuses respectively.  Unlike the normal ``read`` 
function, this variant eschews the data route system and sends the data directly to the Android device.

::

    settings.readCurrentPowerStatusAsync().continueWith(new Continuation<Byte, Void>() {
        @Override
        public Void then(Task<Byte> task) throws Exception {
            Log.i("MainActivity", "power source attached? " + task.getResult();
            return null;
        }
    });