.. highlight:: java

Settings
========

The `Settings <https://mbientlab.com/docs/metawear/android/2/com/mbientlab/metawear/module/Settings.html>`_ module controls board preferences and reports board information.  You can combine preference changes with the macro module to make them permanent.

Advertising Parameters
----------------------

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

::

    import com.mbientlab.metawear.module.Settings;
    
    Settings settingsModule= mwBoard.getModule(Settings.class);
    
    // Change the advertisement name, TX power, and advertising interval
    settingsModule.configure().setDeviceName("AntiWear")
        .setTXPower((byte) -4)
        .setAdvertisingInterval(1024, 100)
        .commit();

Connection Parameters
---------------------

Bluetooth LE connection parameters control how the ble devices communicate with each other.  Configuring thes parameters is done with the `ConnectionParameterEditor <https://mbientlab.com/docs/metawear/android/2/com/mbientlab/metawear/module/Settings.ConnectionParameterEditor.html>`_ interface.  A more detailed explanation on connection parameters can be found on the Nordic Developer Zone forums: `https://devzone.nordicsemi.com/question/60/what-is-connection-parameters/ <https://devzone.nordicsemi.com/question/60/what-is-connection-parameters/>`_.

::

    import com.mbientlab.metawear.module.Settings;
    
    Settings settingsModule= mwBoard.getModule(Settings.class);
    
    // Change connection interval
    settingsModule.configureConnectionParameters()
        .setMinConnectionInterval(10.f)
        .setMaxConnectionInterval(1024.f)
        .commit();

Reading Battery State
---------------------

Reading the battery state is done by calling `readBatteryState <https://mbientlab.com/docs/metawear/android/2/com/mbientlab/metawear/module/Settings.html#readBatteryState()>`_ and the board reports both the battery charge percentage and voltage.  Unlike the battery gatt service, reading the battery state through the Settings mdoule allows you to use the bateery data with the DataSignal interface.

::

    import com.mbientlab.metawear.module.Settings;
    import com.mbientlab.metawear.module.Settings.BatteryState;
    
    Settings settingsModule= mwBoard.getModule(Settings.class);
    
    settingsModule.routeData().fromBattery().stream("battery_state").commit()
        .onComplete(new CompletionHandler<RouteManager>() {
            @Override
            public void success(RouteManager result) {
                result.subscribe("battery_state", new RouteManager.MessageHandler() {
                    @Override
                    public void process(Message msg) {
                        Log.i("MainActivity", "Battery state: " + msg.getData(BatteryState.class));
                    }
                });
            }
        });
    settingsModule.readBatteryState();

Handling Disconnects
--------------------

The board can be programmed to react to a disconnect using a signal monitor.  ::

    import com.mbientlab.metawear.module.Settings;
    
    final Led ledModule= mwBoard.getModule(Led.class);
    Settings settingsModule= mwBoard.getModule(Settings.class);
    
    // Turn on the LED for 5 seconds when disconnected
    settingsModule.handleEvent().fromDisconnect().monitor(new ActivityHandler() {
        @Override
        public void onSignalActive(Map<String, DataProcessor> processors, 
                DataToken token) {
            ledModule.configureColorChannel(Led.ColorChannel.BLUE)
                .setRiseTime((short) 0)
                .setPulseDuration((short) 1000).setRepeatCount((byte) -1)
                .setHighTime((short) 500).setHighIntensity((byte) 16)
                .setLowIntensity((byte) 5).commit();
            ledModule.play(false);
        }
    }).commit(); 

As the disconnect event does not contain any data, it cannot use any DataSignal features unless first transformed with a counter processor.  ::

    // Log disconnect events, requires the counter processor
    settingsModule.handleEvent().fromDisconnect().process(new Counter())
        .log("DISCONNECT_COUNT").commit();

Battery Charging 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.  

Use the 
`fromChargerStatus <https://mbientlab.com/docs/metawear/android/2/com/mbientlab/metawear/module/Settings.SourceSelector.html#fromChargerStatus-->`_ and 
`fromPowerStatus <https://mbientlab.com/docs/metawear/android/2/com/mbientlab/metawear/module/Settings.SourceSelector.html#fromPowerStatus-->`_ methods 
to build a data route for asynchronous notifications from these signal.  ::

    settingsModule.routeData().fromPowerStatus().stream("power").commit()
        .onComplete(new CompletionHandler<RouteManager>() {
            @Override
            public void success(RouteManager result) {
                result.subscribe("power", new MessageHandler() {
                    @Override
                    public void process(Message msg) {
                        Log.i("MainActivity", "Power source attached? " + msg.getData(Byte.class));
                    }
                });
            }
        });

Alternatively, you can explicitly read the charge and power statuses using the 
`readChargeStatus <https://mbientlab.com/docs/metawear/android/2/com/mbientlab/metawear/module/Settings.html#readChargeStatus-->`_ and 
`readPowerStatus <https://mbientlab.com/docs/metawear/android/2/com/mbientlab/metawear/module/Settings.html#readPowerStatus-->`_ methods.  These 
functions do not use the data route system and are used instead to retrieve the current states. ::

    settingsModule.readChargeStatus().onComplete(new CompletionHandler<Byte>() {
        @Override
        public void success(Byte result) {
            Log.i("MainActivity", "Charging? " + result);
        }
    });
    settingsModule.readPowerStatus().onComplete(new CompletionHandler<Byte>() {
        @Override
        public void success(Byte result) {
            Log.i("MainActivity", "Power connected? " + result);
        }
    });