.. highlight:: cpp

Settings
========
The Settings module configures Bluetooth LE parameters and reports diagnostic information about the board.  Functions communicating with this module are 
defined in the `settings.h <https://mbientlab.com/documents/metawear/cpp/0/settings_8h.html>`_ header file.

Battery State
-------------
The battery data provided by the Settings module reports both charge percetange and voltage, encapsulated by the 
`MblMwBatteryState <https://mbientlab.com/documents/metawear/cpp/0/structMblMwBatteryState.html>`_ struct.  Unlike the battery gatt servive, this 
battery data can be utilized with MetaWear features such as the logger. ::

    #include "metawear/core/datasignal.h"
    #include "metawear/core/settings.h"
    #include "metawear/core/types.h"
    
    void battery_stream(MblMwMetaWearBoard* board) {
        auto battery_signal = mbl_mw_settings_get_battery_state_data_signal(board);

        mbl_mw_datasignal_subscribe(battery_signal, nullptr, [](void* context, const MblMwData* data) -> void {
            auto state = (MblMwBatteryState*) data->value;
            printf("{voltage: %dmV, charge: %d}\n", state->voltage, state->charge);
        });
        mbl_mw_datasignal_read(battery_signal);
    }

Handling Disconnects
--------------------
The disconnect event is a type of `MblMwEvent <https://mbientlab.com/documents/metawear/cpp/0/event__fwd_8h.html>`_ 
that is fired when the Bluetooth connection is terminated. ::

    #include "metawear/core/event.h"
    #include "metawear/core/settings.h"
    
    #include "metawear/sensor/accelerometer.h"
    
    void handle_disconnect(MblMwMetaWearBoard* board) {
        static auto cmds_recorded = [](void* context, MblMwEvent* event, int32_t status) {
            printf("commands recorded\n");
        };
    
        auto dc_event = mbl_mw_settings_get_disconnect_event(board);
        mbl_mw_event_record_commands(dc_event);
        // stop the accelerometer when connection is lost
        mbl_mw_acc_stop(board);
        mbl_mw_event_end_record(dc_event, nullptr, cmds_recorded);
    }

Advertising Parameters
----------------------
Advertising parameters control how the Bluetooth radio sends its advertising data.  You can modify the device name, timeout, tx power, and scan 
response.  If you have set an timeout, you can manually begin another advertisement cycle by calling 
`mbl_mw_settings_start_advertising <https://mbientlab.com/documents/metawear/cpp/0/settings_8h.html#aad3d9f431b6e2178dbb5a409ce14cbce>`_. ::

    #include "metawear/core/settings.h"
    
    void modify_ad_params(MblMwMetaWearBoard* board) {
        // change the device name to 'metaware'
        const uint8_t* name = "metaware";
        mbl_mw_settings_set_device_name(board, name, 8);
    }

Connection Parameters
---------------------
Connection parameters control how BTLE devices communicate with each other.  Modifying the connection parameters are all handled at the same time by 
calling 
`mbl_mw_settings_set_connection_parameters <https://mbientlab.com/documents/metawear/cpp/0/settings_8h.html#a1cf3cae052fe7981c26124340a41d66d>`_.  
A more detailed explanation of about BTLE connection parameters can be found on this 
`post <https://devzone.nordicsemi.com/question/60/what-is-connection-parameters/>`_ from the Nordic Developer Zone forums. ::

    #include "metawear/core/settings.h"
    
    void modify_conn_params(MblMwMetaWearBoard* board) {
        mbl_mw_settings_set_connection_parameters(board, 10.f, 1024.f, 0, 6000);
    }

Power and Charge 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 
`mbl_mw_settings_get_power_status_data_signal <https://mbientlab.com/documents/metawear/cpp/0/settings_8h.html#a3469c6609c3418b7f17dd21882ab8cb4>`_ or 
`mbl_mw_settings_get_charge_status_data_signal <https://mbientlab.com/documents/metawear/cpp/0/settings_8h.html#a22653a0a40d3f5d12e5294aebeb166c1>`_ 
is called on an unsupported board.

::

    void setup_power_status(MblMwMetaWearBoard* board, void* context) {
        auto signal = mbl_mw_settings_get_power_status_data_signal(board);
        mbl_mw_datasignal_subscribe(signal, context, [](void* ctx, const MblMwData* data) {
            auto value = *((uint32_t*)data->value);
            cout << "power source " << (value == 0 ? "not attached" : "attached") << endl;
        });
    }

Because the power and charge statuses only send data when their state changes, developers can explicitly request the current states with 
`mbl_mw_settings_read_current_power_status <https://mbientlab.com/documents/metawear/cpp/0/settings_8h.html#a481133ec7b8456386e97bb748755f4e7>`_ and 
`mbl_mw_settings_read_current_charge_status <https://mbientlab.com/documents/metawear/cpp/0/settings_8h.html#aa885aa09ce4b5c4de03157e4a585ba17>`_ respectively.  

If the board does not support these features, the callback functions will receive ``MBL_MW_SETTINGS_POWER_STATUS_UNSUPPORTED`` and 
``MBL_MW_SETTINGS_CHARGE_STATUS_UNSUPPORTED`` respectively.  

::

    void read_current_power_status(MblMwMetaWearBoard* board, void* context) {
        mbl_mw_settings_read_current_power_status(board, context, [](void* ctx, MblMwMetaWearBoard* board, int32_t value) {
            if (value != MBL_MW_SETTINGS_POWER_STATUS_UNSUPPORTED) {
                cout << "Current power status = " << value;
            } else {
                cout << "Power status not supported on this board" << endl;
            }
        });
    }