MetaWear iOS/macOS/tvOS/watchOS API

https://mbientlab.com/iosdocs/latest/
Admin
MetaWear iOS/macOS/tvOS/watchOS API provides a simple way to communicate with MetaWear boards using...
Tokens:109,636
Snippets:306
Trust Score:9.1
Update:1 year ago
Show doc for...
Tokens:
Raw
### Accelerometer Logging Setup and Download

Source: https://mbientlab.com/iosdocs/latest/_sources/logging.rst

Demonstrates a typical scenario for logging accelerometer data. It involves getting the acceleration signal, logging it, starting the logger, enabling and starting accelerometer sampling, and then stopping sampling, subscribing to logger events, and initiating data download.

```swift
func accelerometerStartLog() {
    let signal = mbl_mw_acc_bosch_get_acceleration_data_signal(device.board)!
    mbl_mw_datasignal_log(signal, bridge(obj: self)) { (context, logger) in
        // Save logger for StopLog()
    }
    mbl_mw_logging_start(device.board, 0)
    mbl_mw_acc_enable_acceleration_sampling(device.board)
    mbl_mw_acc_start(device.board)
}

func accelerometerStopLog(logger:OpaquePointer) {
    mbl_mw_acc_stop(device.board)
    mbl_mw_acc_disable_acceleration_sampling(device.board)
    mbl_mw_logger_subscribe(logger, bridge(obj: self)) { (context, obj) in
        let acceleration: MblMwCartesianFloat = obj!.pointee.valueAs()
        DispatchQueue.main.async {
            print(acceleration.x, acceleration.y, acceleration.z)
        }
    }
    var handlers = MblMwLogDownloadHandler()
    handlers.context = bridgeRetained(obj: self)
    handlers.received_progress_update = { (context, remainingEntries, totalEntries) in
        let progress = Double(totalEntries - remainingEntries) / Double(totalEntries)
        print(progress)
    }
    handlers.received_unknown_entry = { (context, id, epoch, data, length) in
        print("received_unknown_entry")
    }
    handlers.received_unhandled_entry = { (context, data) in
        print("received_unhandled_entry")
    }
    mbl_mw_logging_download(device.board, 100, &handlers)
}
```

--------------------------------

### Swift Example: Start and Stop Accelerometer Logging

Source: https://mbientlab.com/iosdocs/latest/tutorials/SwApple

Demonstrates how to start logging accelerometer data using the MetaWear SDK in Swift. It includes enabling sampling, starting the accelerometer, and initiating the logging process. The stop function shows how to remove loggers, subscribe to data, and download logged data with progress handlers.

```Swift
func accelerometerBMI160StartLog(_ sender: Any) {
    let signal = mbl_mw_acc_bosch_get_acceleration_data_signal(device.board)!
    mbl_mw_datasignal_log(signal, bridge(obj: self)) { (context, logger) in
        let _self: DeviceDetailViewController = bridge(ptr: context!)
        let cString = mbl_mw_logger_generate_identifier(logger)!
        let identifier = String(cString: cString)
        _self.loggers[identifier] = logger!
    }
    mbl_mw_logging_start(device.board, 0)
    mbl_mw_acc_enable_acceleration_sampling(device.board)
    mbl_mw_acc_start(device.board)
}

func accelerometerBMI160StopLog(_ sender: Any) {
    guard let logger = loggers.removeValue(forKey: "acceleration") else {
        return
    }
    mbl_mw_acc_stop(device.board)
    mbl_mw_acc_disable_acceleration_sampling(device.board)
    mbl_mw_logger_subscribe(logger, bridge(obj: self)) { (context, obj) in
        let acceleration: MblMwCartesianFloat = obj!.pointee.valueAs()
    }
    var handlers = MblMwLogDownloadHandler()
    handlers.context = bridgeRetained(obj: self)
    handlers.received_progress_update = { (context, remainingEntries, totalEntries) in
        let _self: DeviceDetailViewController = bridge(ptr: context!)
        let progress = Double(totalEntries - remainingEntries) / Double(totalEntries)
        if remainingEntries == 0 {
            _self.logCleanup { error in
                DispatchQueue.main.async {
                    if error != nil {
                        _self.deviceConnected()
                    }
                }
            }
        }
    }
    handlers.received_unknown_entry = { (context, id, epoch, data, length) in
        print("received_unknown_entry")
    }
    handlers.received_unhandled_entry = { (context, data) in
        print("received_unhandled_entry")
    }
    mbl_mw_logging_download(device.board, 100, &handlers)
}
```

--------------------------------

### Swift RSS Data Processor Example

Source: https://mbientlab.com/iosdocs/latest/tutorials/SwApple

Demonstrates how to create and subscribe to a Root Sum Square (RSS) data processor for acceleration data in Swift. This example shows chaining processors and handling data streams, including setup and cleanup for sampling.

```swift
let signal = mbl_mw_acc_bosch_get_acceleration_data_signal(device.board)

// Create RSS
signal!.rssCreate().continueOnSuccessWith { rss in
    self.streamingCleanup[signal!] = {
        mbl_mw_acc_stop(self.device.board)
        mbl_mw_acc_disable_acceleration_sampling(self.device.board)
        mbl_mw_datasignal_unsubscribe(rss)
    }
    mbl_mw_datasignal_subscribe(rss, bridge(obj: self)) { (context, obj) in
        let acceleration_rss: MblMwCartesianFloat = obj!.pointee.valueAs()
        print(acceleration_rss)
    }
    mbl_mw_acc_enable_acceleration_sampling(self.device.board)
    mbl_mw_acc_start(self.device.board)
}

```

--------------------------------

### Record LED Blink Macro for Boot Execution

Source: https://mbientlab.com/iosdocs/latest/_sources/macro.rst

An example demonstrating how to record a sequence of commands to set up an LED pattern that executes on device boot. It includes starting recording, configuring the LED pattern, playing it, and then ending the recording session.

```cpp
// Record everything to startup macro
mbl_mw_macro_record(device.board, 1)

// Setup LED
mbl_mw_led_stop_and_clear(device.board)
// Success flash
var greenPattern = MblMwLedPattern(high_intensity: 31,
                                        low_intensity: 0,
                                        rise_time_ms: 100,
                                        high_time_ms: 200,
                                        fall_time_ms: 100,
                                        pulse_duration_ms: 800,
                                        delay_time_ms: 0,
                                        repeat_count: 3)
mbl_mw_led_write_pattern(device.board, &greenPattern, MBL_MW_LED_COLOR_GREEN)
mbl_mw_led_play(device.board)

// Finish off this macro
device.macroEndRecord()
```

--------------------------------

### Install CocoaPods Dependency

Source: https://mbientlab.com/iosdocs/latest/_sources/project.rst

This command installs the dependencies specified in your Podfile, including the MetaWear SDK, after you have added it to your project's Podfile.

```console
pod install
```

--------------------------------

### Scan for MetaWear Device and Flash LED in Swift

Source: https://mbientlab.com/iosdocs/latest/project

This Swift code demonstrates how to scan for a MetaWear board, connect to it, and flash its LED. It uses the `MetaWearScanner` to find devices and the `connectAndSetup` method. The example includes error handling and uses the MetaWear C++ SDK functions to control the LED.

```Swift
import MetaWear
import MetaWearCpp

MetaWearScanner.shared.startScan(allowDuplicates: true) { (device) in
    // We found a MetaWear board, see if it is close
    if device.rssi.intValue > -50 {
        // Hooray! We found a MetaWear board, so stop scanning for more
        MetaWearScanner.shared.stopScan()
        // Connect to the board we found
        device.connectAndSetup().continueWith { t in
            if let error = t.error {
                // Sorry we couldn't connect
                print(error)
            } else {
                // Hooray! We connected to a MetaWear board, so flash its LED!
                var pattern = MblMwLedPattern()
                mbl_mw_led_load_preset_pattern(&pattern, MBL_MW_LED_PRESET_PULSE)
                mbl_mw_led_stop_and_clear(device.board)
                mbl_mw_led_write_pattern(device.board, &pattern, MBL_MW_LED_COLOR_GREEN)
                mbl_mw_led_play(device.board)
            }
        }
    }
}
```

--------------------------------

### Accelerometer Logging and Download Setup (Swift)

Source: https://mbientlab.com/iosdocs/latest/logging

Demonstrates the process of starting accelerometer data logging and stopping it, including subscribing to data callbacks and initiating a download with custom handlers for progress and received data. This setup is crucial for collecting sensor data from MbientLab devices.

```Swift
func accelerometerStartLog() {
    let signal = mbl_mw_acc_bosch_get_acceleration_data_signal(device.board)!
    mbl_mw_datasignal_log(signal, bridge(obj: self)) { (context, logger) in
        // Save logger for StopLog()
    }
    mbl_mw_logging_start(device.board, 0)
    mbl_mw_acc_enable_acceleration_sampling(device.board)
    mbl_mw_acc_start(device.board)
}

func accelerometerStopLog(logger:OpaquePointer) {
    mbl_mw_acc_stop(device.board)
    mbl_mw_acc_disable_acceleration_sampling(device.board)
    mbl_mw_logger_subscribe(logger, bridge(obj: self)) { (context, obj) in
        let acceleration: MblMwCartesianFloat = obj!.pointee.valueAs()
        DispatchQueue.main.async {
            print(acceleration.x, acceleration.y, acceleration.z)
        }
    }
    var handlers = MblMwLogDownloadHandler()
    handlers.context = bridgeRetained(obj: self)
    handlers.received_progress_update = { (context, remainingEntries, totalEntries) in
        let progress = Double(totalEntries - remainingEntries) / Double(totalEntries)
        print(progress)
    }
    handlers.received_unknown_entry = { (context, id, epoch, data, length) in
        print("received_unknown_entry")
    }
    handlers.received_unhandled_entry = { (context, data) in
        print("received_unhandled_entry")
    }
    mbl_mw_logging_download(device.board, 100, &handlers)
}
```

--------------------------------

### Install Git using Homebrew

Source: https://mbientlab.com/iosdocs/latest/tutorials/SwApple

Installs Git using the Homebrew package manager. This is an alternative method if Git is not pre-installed or if you prefer managing it via Homebrew.

```bash
brew install git
```

--------------------------------

### Schedule Timer Tasks and Subscribe to Data

Source: https://mbientlab.com/iosdocs/latest/tutorials/SwApple

This example shows how to create and manage MetaWear timers for scheduling periodic tasks. It includes subscribing to a data signal, creating a timer with a specified period, recording commands to read the signal when the timer fires, and starting the timer. Cleanup logic to unsubscribe and remove the timer is also provided.

```swift
let signal = mbl_mw_multi_chnl_temp_get_temperature_data_signal(device.board, 1)!
mbl_mw_datasignal_subscribe(signal, bridge(obj: self)) { (context, obj) in
    let temp: UInt32 = obj!.pointee.valueAs()
    print(format: "%d", temp)
}
// Create a timer to read every 700 ms
device.timerCreate(period: 700).continueOnSuccessWith { timer in
    self.streamingCleanup[signal] = {
        mbl_mw_timer_remove(timer)
        mbl_mw_datasignal_unsubscribe(signal)
    }
    mbl_mw_event_record_commands(timer)
    mbl_mw_datasignal_read(signal)
    timer.eventEndRecord().continueOnSuccessWith {
        mbl_mw_timer_start(timer)
    }
}
```

--------------------------------

### Example: LED Blink on Boot Macro (Swift API)

Source: https://mbientlab.com/iosdocs/latest/macro

Demonstrates recording a sequence of commands to the MetaWear device's startup macro. This example configures the LED to blink green three times on boot. It uses the Swift API for recording and LED pattern configuration.

```Swift
// Record everything to startup macro
mbl_mw_macro_record(device.board, 1)

// Setup LED
mbl_mw_led_stop_and_clear(device.board)
// Success flash
var greenPattern = MblMwLedPattern(high_intensity: 31,
                                    low_intensity: 0,
                                    rise_time_ms: 100,
                                    high_time_ms: 200,
                                    fall_time_ms: 100,
                                    pulse_duration_ms: 800,
                                    delay_time_ms: 0,
                                    repeat_count: 3)
mbl_mw_led_write_pattern(device.board, &greenPattern, MBL_MW_LED_COLOR_GREEN)
mbl_mw_led_play(device.board)

// Finish off this macro
device.macroEndRecord()
```

--------------------------------

### Add MetaWear Dependency with CocoaPods

Source: https://mbientlab.com/iosdocs/latest/_sources/project.rst

This snippet shows how to add the MetaWear SDK, including optional subspecs for UI, AsyncUtils, Mocks, and DFU, to your project's Podfile. After updating the Podfile, run 'pod install' in the console to fetch and integrate the dependency.

```ruby
# The subspecs are all optional, but might be useful
pod "MetaWear", :subspecs => ['UI', 'AsyncUtils', 'Mocks', 'DFU']
```

--------------------------------

### CocoaPods Install and Update

Source: https://mbientlab.com/iosdocs/latest/tutorials/SwApple

Commands to install or update dependencies after modifying the Podfile. 'pod install' installs the specified pods, and 'pod update' fetches the latest compatible versions.

```shell
pod install
```

```shell
pod update
```

--------------------------------

### Start Streaming Accelerometer Data (Swift)

Source: https://mbientlab.com/iosdocs/latest/tutorials/SwApple

This snippet demonstrates how to configure, start, and subscribe to accelerometer data from a MetaWear board using Swift. It sets the accelerometer's range and output data rate, subscribes to the acceleration data signal, and defines a callback to print the Cartesian coordinates. It also includes logic for cleaning up the stream.

```swift
func accelerometerBMI160StartStreamPressed(_ sender: Any) {
     mbl_mw_acc_bosch_set_range(device.board, MBL_MW_ACC_BOSCH_RANGE_2G)
     mbl_mw_acc_set_odr(device.board, 25.f)
     mbl_mw_acc_bosch_write_acceleration_config(device.board)
     let signal = mbl_mw_acc_bosch_get_acceleration_data_signal(device.board)!
     mbl_mw_datasignal_subscribe(signal, bridge(obj: self)) { (context, obj) in
         let acceleration: MblMwCartesianFloat = obj!.pointee.valueAs()
         print(Double(acceleration.x), Double(acceleration.y), Double(acceleration.z))
         }
     }
     mbl_mw_acc_enable_acceleration_sampling(device.board)
     mbl_mw_acc_start(device.board)

     streamingCleanup[signal] = {
         mbl_mw_acc_stop(self.device.board)
         mbl_mw_acc_disable_acceleration_sampling(self.device.board)
         mbl_mw_datasignal_unsubscribe(signal)
     }
 }
```

--------------------------------

### Add MetaWear Dependency with CocoaPods

Source: https://mbientlab.com/iosdocs/latest/project

This snippet shows how to add the MetaWear SDK as a dependency to your Xcode project using CocoaPods. It specifies the required subspecs for UI, AsyncUtils, Mocks, and DFU. After adding the line to your Podfile, run `pod install`.

```Shell
# The subspecs are all optional, but might be useful
pod "MetaWear", :subspecs => ['UI', 'AsyncUtils', 'Mocks', 'DFU']

pod install
```

--------------------------------

### Install Homebrew Package Manager

Source: https://mbientlab.com/iosdocs/latest/tutorials/SwApple

Installs the Homebrew package manager on macOS. Homebrew simplifies the installation of software and developer tools. It requires Ruby and a shell environment.

```ruby
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
```

--------------------------------

### MetaWear CocoaPod Integration

Source: https://mbientlab.com/iosdocs/latest/tutorials/SwApple

Instructions for adding the MetaWear SDK to an Xcode project using CocoaPods. This involves specifying the MetaWear pod and its subspecs in the Podfile, followed by running the install command.

```ruby
pod "MetaWear", :subspecs => ['UI', 'AsyncUtils', 'Mocks', 'DFU']
```

--------------------------------

### CocoaPods Installation

Source: https://mbientlab.com/iosdocs/latest/tutorials/SwApple

Command to install the CocoaPods dependency manager, which is essential for managing Swift and Objective-C Cocoa projects. It requires Ruby and may need administrator privileges.

```shell
sudo gem install cocoapods
```

--------------------------------

### Data Processor Creation Examples

Source: https://mbientlab.com/iosdocs/latest/_sources/dataprocessor.rst

Illustrates how to create different data processors using C++ functions, which are often wrapped by higher-level iOS APIs. These examples show the basic function calls for creating processors like RMS and Threshold.

```APIDOC
Processor Creation Functions:

- `rmsCreate()`: Creates an RMS (Root Mean Square) data processor.
- `thresholdCreate(mode:boundary:hysteresis:)`: Creates a Threshold data processor with specified mode, boundary, and hysteresis.
- `sampleCreate(binSize:)`: Creates a Sample data processor with a defined bin size.
```

--------------------------------

### RubyGems Management Commands

Source: https://mbientlab.com/iosdocs/latest/tutorials/SwApple

Common commands for managing RubyGems, the Ruby package manager. This includes checking installation, updating the system, installing gems, listing installed gems, checking for outdated gems, and cleaning up old versions.

```shell
which gem
```

```shell
gem update --system
```

```shell
gem install <gemname>
```

```shell
gem install <gemname> --no-document
```

```shell
gem list
```

```shell
gem outdated
```

```shell
gem update [<gemname>]
```

```shell
gem cleanup
```

--------------------------------

### Check Git Version

Source: https://mbientlab.com/iosdocs/latest/tutorials/SwApple

Checks the installed version of Git, a distributed version-control system. This command is used to confirm if Git is installed and accessible from the command line.

```bash
git --version
```

--------------------------------

### Start Gyroscope Data Stream (Swift)

Source: https://mbientlab.com/iosdocs/latest/tutorials/SwApple

Configures and starts streaming gyroscope data from a MetaWear device. It subscribes to the rotation data signal, prints the epoch and gyroscope values, and sets up cleanup routines.

```swift
func gyroBMI160StartStream(_ sender: Any) {
    let signal = mbl_mw_gyro_bmi160_get_rotation_data_signal(device.board)!
    mbl_mw_datasignal_subscribe(signal, bridge(obj: self)) { (context, obj) in
        let gyroscope: MblMwCartesianFloat = obj!.pointee.valueAs()
        print(obj!.pointee.epoch, gyroscope, gyroscope.x, gyroscope.y, gyroscope.z)
    }
    mbl_mw_gyro_bmi160_enable_rotation_sampling(device.board)
    mbl_mw_gyro_bmi160_start(device.board)

    streamingCleanup[signal] = {
        mbl_mw_gyro_bmi160_stop(self.device.board)
        mbl_mw_gyro_bmi160_disable_rotation_sampling(self.device.board)
        mbl_mw_datasignal_unsubscribe(signal)
    }
}
```

--------------------------------

### MetaWear Swift/C++ Imports

Source: https://mbientlab.com/iosdocs/latest/tutorials/SwApple

How to import the MetaWear framework header files into your Swift or Objective-C code to start using the MetaWear functionalities.

```swift
import MetaWear
```

```swift
import MetaWearCpp
```

--------------------------------

### Check Command Line Tools Installation

Source: https://mbientlab.com/iosdocs/latest/tutorials/SwApple

Verifies if the Command Line Tools (CLT) for Xcode are installed on your macOS system. This is a prerequisite for many development tools, including Homebrew.

```bash
xcode-select -p
```

--------------------------------

### APIDOC: Logging Functions

Source: https://mbientlab.com/iosdocs/latest/tutorials/SwApple

Provides functions for creating, managing, and interacting with data loggers on MetaWear devices. This includes starting and stopping logging, subscribing to logger events, and downloading logged data.

```APIDOC
MblMwDataLogger*
mbl_mw_datasignal_log(const MblMwDataSignal* signal, void* context, MblMwDataLoggerCallback callback)
  - Creates a data logger for a specific data signal.
  - Parameters:
    - signal: The MblMwDataSignal to log.
    - context: User defined context passed to the callback.
    - callback: Callback function executed upon logger creation. Receives context and a pointer to the created MblMwDataLogger or null on failure.
  - Returns: A pointer to the created MblMwDataLogger on success, NULL on failure.

uint32_t
mbl_mw_logger_get_id(const MblMwDataLogger* logger)
  - Retrieves the unique numerical ID of a data logger.
  - Parameters:
    - logger: The MblMwDataLogger object.
  - Returns: The logger's ID.

const MblMwDataLogger*
mbl_mw_logger_lookup_id(MblMwDevice* device, uint32_t id)
  - Retrieves a logger from the device's internal storage using its ID.
  - Parameters:
    - device: The MetaWear device.
    - id: The ID of the logger to retrieve.
  - Returns: A pointer to the logger if found, NULL otherwise.

void
mbl_mw_logger_subscribe(const MblMwDataLogger* logger, void* context, MblMwDataLoggerSubscribeCallback callback)
  - Attaches a callback function to a logger to process downloaded data.
  - Parameters:
    - logger: The MblMwDataLogger to subscribe to.
    - context: User defined context passed to the callback.
    - callback: Callback function that handles received data. It receives the context and a pointer to the MblMwDataLogger object containing the data.

void
mbl_mw_logging_start(MblMwDevice* device, uint32_t log_change_delay_ms)
  - Starts all configured loggers on the device.
  - Parameters:
    - device: The MetaWear device.
    - log_change_delay_ms: Delay in milliseconds before logging starts after configuration changes (0 for immediate).

void
mbl_mw_logging_download(MblMwDevice* device, uint32_t max_samples, MblMwLogDownloadHandler* handler)
  - Initiates the download of logged data from the device.
  - Parameters:
    - device: The MetaWear device.
    - max_samples: Maximum number of samples to download per entry (0 for all).
    - handler: A pointer to an MblMwLogDownloadHandler struct to manage download progress and data reception.

// Related Sensor API Calls (for context)

MblMwDataSignal*
mbl_mw_acc_bosch_get_acceleration_data_signal(MblMwDevice* device)
  - Gets the data signal for Bosch BMI160 accelerometer data.
  - Parameters:
    - device: The MetaWear device.
  - Returns: Pointer to the acceleration data signal.

void
mbl_mw_acc_enable_acceleration_sampling(MblMwDevice* device)
  - Enables accelerometer sampling.
  - Parameters:
    - device: The MetaWear device.

void
mbl_mw_acc_start(MblMwDevice* device)
  - Starts the accelerometer sensor.
  - Parameters:
    - device: The MetaWear device.

void
mbl_mw_acc_stop(MblMwDevice* device)
  - Stops the accelerometer sensor.
  - Parameters:
    - device: The MetaWear device.

void
mbl_mw_acc_disable_acceleration_sampling(MblMwDevice* device)
  - Disables accelerometer sampling.
  - Parameters:
    - device: The MetaWear device.

// MblMwLogDownloadHandler struct definition (for reference)
// struct MblMwLogDownloadHandler {
//     void *context;
//     void (*received_progress_update)(void *context, uint32_t remainingEntries, uint32_t totalEntries);
//     void (*received_unknown_entry)(void *context, uint32_t id, uint64_t epoch, const uint8_t *data, uint16_t length);
//     void (*received_unhandled_entry)(void *context, const uint8_t *data);
// };
```

--------------------------------

### Start On-Board Logging

Source: https://mbientlab.com/iosdocs/latest/_sources/logging.rst

Initiates the on-board logging process on the device. This function is essential before data can be recorded. It requires the device board and a flag, typically set to 0 for default behavior.

```swift
mbl_mw_logging_start(device.board, 0)
```

--------------------------------

### Retrieve Z-Axis Accelerometer Data

Source: https://mbientlab.com/iosdocs/latest/_sources/datasignal.rst

This Swift example demonstrates how to get the Z-axis component of the accelerometer data signal and subscribe to its updates.

```swift
let acc_root = mbl_mw_acc_get_acceleration_data_signal(board);
let acc_z = mbl_mw_datasignal_get_component(acc_root, MBL_MW_ACC_ACCEL_Z_AXIS_INDEX);

mbl_mw_datasignal_subscribe(acc_z, bridge(obj: self)) { (context, obj) in
    let value: UInt32 = obj!.pointee.valueAs()
    print(value)
}
```

--------------------------------

### Measure Illuminance (Swift)

Source: https://mbientlab.com/iosdocs/latest/ambientlightsensor

Starts illuminance measurements from the Ambient Light Sensor and subscribes to the data signal. The illuminance is returned as an unsigned integer representing milli lux. The example shows how to retrieve the data signal, subscribe a callback, and then start the sensor measurement.

```swift
let signal = mbl_mw_als_ltr329_get_illuminance_data_signal(device.board)!
mbl_mw_datasignal_subscribe(signal, bridge(obj: self)) { (context, obj) in
    let illuminance: UInt32 = obj!.pointee.valueAs()
    print(String(format: "%.3f lux", Double(illuminance) / 1000.0))
}
mbl_mw_als_ltr329_start(device.board)
```

--------------------------------

### Retrieve Accelerometer Z-Axis Component

Source: https://mbientlab.com/iosdocs/latest/datasignal

This example shows how to retrieve a specific component of a multi-valued signal, in this case, the z-axis component of the accelerometer data. It involves getting the root signal, extracting the component, and subscribing to its values.

```swift
acc_root = mbl_mw_acc_get_acceleration_data_signal(board)
acc_z = mbl_mw_datasignal_get_component(acc_root, MBL_MW_ACC_ACCEL_Z_AXIS_INDEX)
mbl_mw_datasignal_subscribe(acc_z, bridge(obj: self)) { (context, obj) in
    let value: UInt32 = obj!.pointee.valueAs()
    print(value)
}
```

--------------------------------

### Control On-board LED Pattern (Swift)

Source: https://mbientlab.com/iosdocs/latest/tutorials/SwApple

Shows how to control the on-board RGB LED by loading a preset pattern, writing it to the device, and then playing it. This involves configuring the LED pattern and managing its playback state.

```swift
device.connectAndSetup().continueWith { t in
    var pattern = MblMwLedPattern()
    mbl_mw_led_load_preset_pattern(&pattern, MBL_MW_LED_PRESET_PULSE)
    mbl_mw_led_stop_and_clear(device.board)
    mbl_mw_led_write_pattern(device.board, &pattern, MBL_MW_LED_COLOR_GREEN)
    mbl_mw_led_play(device.board)
}
```

--------------------------------

### Connect to MetaWear Device (Swift)

Source: https://mbientlab.com/iosdocs/latest/tutorials/SwApple

Scans for nearby MetaWear devices and connects to the closest one based on RSSI. This Swift code snippet demonstrates the initial setup for establishing a connection and initializing the MetaWear board's state.

```Swift
import MetaWear
import MetaWearCpp

MetaWearScanner.shared.startScan(allowDuplicates: true) { (device) in
    // We found a MetaWear board, see if it is close
    if device.rssi.intValue > -50 {
        // Hooray! We found a MetaWear board, so stop scanning for more
        MetaWearScanner.shared.stopScan()
        // Connect to the board we found
        device.connectAndSetup().continueWith { t in
            if let error = t.error {
                // Sorry we couldn't connect
                print(error)
            }
        }
    }
}

```

--------------------------------

### Access Component Values from Data Signals

Source: https://mbientlab.com/iosdocs/latest/tutorials/SwApple

This snippet demonstrates how to retrieve individual components from multi-value data signals, such as the X, Y, or Z components of acceleration. It uses `mbl_mw_datasignal_get_component` to get a specific component and then subscribes to it. It also includes enabling and starting the acceleration sensor and associated cleanup.

```swift
let signal = mbl_mw_acc_bosch_get_acceleration_data_signal(device.board)!
let signal_x = mbl_mw_datasignal_get_component(signal, Const.ACC_ACCEL_X_AXIS_INDEX)!

mbl_mw_datasignal_subscribe(signal_x, bridge(obj: self)) { (context, obj) in
    let accelerationx: MblMwCartesianFloat = obj!.pointee.valueAs()
    print(Double(accelerationx))
}

mbl_mw_acc_enable_acceleration_sampling(device.board)
mbl_mw_acc_start(device.board)

streamingCleanup[signal] = {
    mbl_mw_acc_stop(self.device.board)
    mbl_mw_acc_disable_acceleration_sampling(self.device.board)
    mbl_mw_datasignal_unsubscribe(signal_x)
}
```

--------------------------------

### Connect to MetaWear Board (Swift)

Source: https://mbientlab.com/iosdocs/latest/metawearboard

Initiates a Bluetooth LE connection and sets up the MetaWear board. The returned task completes when the connection is established and the board is initialized. Handles connection success, cancellation, or errors.

```Swift
device.connectAndSetup().continueWith { t in
    if t.isCancelled {
        print("cancelConnection() called before connection completed")
    } else if t.isFaulted {
        print("Connection Error: (t.error?.localizedDescription ?? "N/A")")
    } else {
        print("Connection Success")
    }
}
```

--------------------------------

### Scan, Connect, and Flash LED on MetaWear Board

Source: https://mbientlab.com/iosdocs/latest/_sources/project.rst

This Swift code demonstrates how to scan for MetaWear devices, connect to the nearest one (based on RSSI), and then flash the board's LED green using the MetaWear C API. It includes error handling for connection failures.

```swift
import MetaWear
import MetaWearCpp

MetaWearScanner.shared.startScan(allowDuplicates: true) { (device) in
    // We found a MetaWear board, see if it is close
    if device.rssi.intValue > -50 {
        // Hooray! We found a MetaWear board, so stop scanning for more
        MetaWearScanner.shared.stopScan()
        // Connect to the board we found
        device.connectAndSetup().continueWith { t in
            if let error = t.error {
                // Sorry we couldn't connect
                print(error)
            } else {
                // Hooray! We connected to a MetaWear board, so flash its LED!
                var pattern = MblMwLedPattern()
                mbl_mw_led_load_preset_pattern(&pattern, MBL_MW_LED_PRESET_PULSE)
                mbl_mw_led_stop_and_clear(device.board)
                mbl_mw_led_write_pattern(device.board, &pattern, MBL_MW_LED_COLOR_GREEN)
                mbl_mw_led_play(device.board)
            }
        }
    }
}
```

--------------------------------

### MetaWear SDK Git Repository

Source: https://mbientlab.com/iosdocs/latest/tutorials/SwApple

Commands to clone the MetaWear SDK for iOS, macOS, and tvOS from GitHub. This includes cloning the main repository and ensuring submodules are downloaded, which is crucial for the C++ components.

```git
git clone https://github.com/mbientlab/MetaWear-SDK-iOS-macOS-tvOS.git
```

```git
git clone --recurse-submodules https://github.com/mbientlab/MetaWear-SDK-iOS-macOS-tvOS.git
```

--------------------------------

### Record Commands for MetaWear Events

Source: https://mbientlab.com/iosdocs/latest/tutorials/SwApple

This snippet demonstrates how to program the MetaWear board to execute commands in response to an event. It involves getting an event, recording commands using `mbl_mw_event_record_commands`, and then ending the recording state with `mbl_mw_event_end_record`. This allows for asynchronous execution of board actions when a specific event fires.

```cpp
event = mbl_mw_settings_get_disconnect_event(device.board);
var pattern = MblMwLedPattern(high_intensity: 31, low_intensity: 31, rise_time_ms: 0, high_time_ms: 2000, fall_time_ms: 0, pulse_duration_ms: 2000, delay_time_ms: 0, repeat_count: 0xFF)

mbl_mw_event_record_commands(event)
mbl_mw_led_write_pattern(device.board, &pattern, color)
mbl_mw_led_play(device.board)

event.eventEndRecord()
```

--------------------------------

### Comparator Data Processor (Swift)

Source: https://mbientlab.com/iosdocs/latest/dataprocessor

Creates a comparator data processor that filters out data not satisfying a comparison operation. Callers can force signed or unsigned comparisons, or let the API decide. The output data type ID is the same as the input source. This example shows a basic comparator setup.

```swift
let signal = mbl_mw_gpio_get_pin_monitor_data_signal(device.board, pin)!
signal.comparatorCreate(0,0,[8])
```

--------------------------------

### Macro Recording and Execution

Source: https://mbientlab.com/iosdocs/latest/tutorials/SwApple

Explains how to record sequences of MetaWear commands into the device's flash memory for later execution. This includes entering macro mode, programming commands, exiting macro mode, and options for execution on boot or erasing all macros.

```C
// Record everything to macro
mbl_mw_macro_record(device.board, 1)
var redPattern = MblMwLedPattern(high_intensity: 10,
                                low_intensity: 0,
                                rise_time_ms: 100,
                                high_time_ms: 200,
                                fall_time_ms: 100,
                                pulse_duration_ms: 15000,
                                delay_time_ms: 2400,
                                repeat_count: 0xFF)
mbl_mw_led_write_pattern(device.board, &redPattern, MBL_MW_LED_COLOR_RED)
mbl_mw_led_play(device.board)

// Finish off this macro
return device.macroEndRecord()

```

--------------------------------

### Schedule Periodic Humidity Readings (Swift/C)

Source: https://mbientlab.com/iosdocs/latest/timer

This example demonstrates scheduling periodic humidity readings using the MetaWear timer API. It configures the BME280 humidity sensor, subscribes to its data signal, creates a timer to read every 700ms, and then starts the timer. It also includes logic to remove the timer and unsubscribe from the signal when done.

```C
mbl_mw_humidity_bme280_set_oversampling(device.board, MBL_MW_HUMIDITY_BME280_OVERSAMPLING_16X)
```

```Swift
let signal = mbl_mw_humidity_bme280_get_percentage_data_signal(device.board)!

mbl_mw_datasignal_subscribe(signal, bridge(obj: self)) { (context, obj) in
    let humidity: Float = obj!.pointee.valueAs()
    print(String(format: "%.2f", humidity))
}

// Create a timer to read every 700 ms
device.timerCreate(period: 700).continueOnSuccessWith {
    // Timer configuration block
    mbl_mw_timer_remove($0)
    mbl_mw_datasignal_unsubscribe(signal)
    mbl_mw_event_record_commands($0)
    mbl_mw_datasignal_read(signal)
    // End timer configuration and start
    $0.eventEndRecord().continueOnSuccessWith {
        mbl_mw_timer_start($0)
    }
}
```

--------------------------------

### Enable Rotation Sampling and Subscribe to Data (Swift)

Source: https://mbientlab.com/iosdocs/latest/gyro

Enables gyroscope rotation rate sampling and subscribes to the angular velocity data signal. The angular velocity is provided as a `MblMwCartesianFloat` struct, representing spin around the X, Y, and Z axes in degrees per second. Includes setup for starting the sensor and defining a cleanup callback.

```Swift
let signal = mbl_mw_gyro_bmi160_get_rotation_data_signal(device.board)!
mbl_mw_datasignal_subscribe(signal, bridge(obj: self)) { (context, obj) in
    let gyro: MblMwCartesianFloat = obj!.pointee.valueAs()
    print(Double(gyro.x ), Double(gyro.y), Double(gyro.z))
}
mbl_mw_gyro_bmi160_enable_rotation_sampling(device.board)
mbl_mw_gyro_bmi160_start(device.board)

streamingCleanup[signal] = { //Callback
    mbl_mw_gyro_bmi160_stop(self.device.board)
    mbl_mw_gyro_bmi160_disable_rotation_sampling(self.device.board)
    mbl_mw_datasignal_unsubscribe(signal)
}
```

--------------------------------

### Enable and Subscribe to Orientation Detection Data

Source: https://mbientlab.com/iosdocs/latest/accelerometer

This snippet demonstrates how to enable orientation detection on a device, subscribe to its data signal, and process the orientation changes. It uses the MbientLab SDK functions to get the data signal, subscribe to it with a callback, and then enable and start the accelerometer. A cleanup block is provided to stop the accelerometer, disable orientation detection, and unsubscribe from the signal.

```swift
let signal = mbl_mw_acc_bosch_get_orientation_detection_data_signal(device.board)!
mbl_mw_datasignal_subscribe(signal, bridge(obj: self)) { (context, obj) in
    let orientation: MblMwSensorOrientation = obj!.pointee.valueAs()
    switch orientation {
        case MBL_MW_SENSOR_ORIENTATION_FACE_UP_PORTRAIT_UPRIGHT:
            print("Portrait Face Up")
        case MBL_MW_SENSOR_ORIENTATION_FACE_UP_PORTRAIT_UPSIDE_DOWN:
            print("Portrait Upside Down Face Up")
        case MBL_MW_SENSOR_ORIENTATION_FACE_UP_LANDSCAPE_LEFT:
            print("Landscape Left Face Up")
        case MBL_MW_SENSOR_ORIENTATION_FACE_UP_LANDSCAPE_RIGHT:
            print("Landscape Right Face Up")
        case MBL_MW_SENSOR_ORIENTATION_FACE_DOWN_PORTRAIT_UPRIGHT:
            print("Portrait Face Down")
        case MBL_MW_SENSOR_ORIENTATION_FACE_DOWN_PORTRAIT_UPSIDE_DOWN:
            print("Portrait Upside Down Face Down")
        case MBL_MW_SENSOR_ORIENTATION_FACE_DOWN_LANDSCAPE_LEFT:
            print("Landscape Left Face Down")
        case MBL_MW_SENSOR_ORIENTATION_FACE_DOWN_LANDSCAPE_RIGHT:
            print("Landscape Right Face Down")
        default:
            print("N/A")
        }
}
mbl_mw_acc_bosch_enable_orientation_detection(device.board)
mbl_mw_acc_start(device.board)

streamingCleanup[signal] = { //Callback when user us done streaming
    mbl_mw_acc_stop(self.device.board)
    mbl_mw_acc_bosch_disable_orientation_detection(self.device.board)
    mbl_mw_datasignal_unsubscribe(signal)
}
```

--------------------------------

### LED Pattern Configuration and Playback

Source: https://mbientlab.com/iosdocs/latest/_sources/led.rst

Demonstrates how to configure a custom LED pattern, write it to the board, and initiate playback. This involves defining pattern parameters like intensity and timing, clearing previous patterns, and then playing the new sequence. It utilizes functions from the led.h header.

```cpp
/*
 * Example of setting a custom LED pattern and playing it.
 * This code assumes a device object and a color variable are available.
 */

// Define a custom LED pattern
// Parameters: high_intensity, low_intensity, rise_time_ms, high_time_ms, fall_time_ms, pulse_duration_ms, delay_time_ms, repeat_count
// Note: The exact syntax for MblMwLedPattern initialization might vary slightly based on the C++ binding or wrapper used.
// The example below uses a Swift-like syntax for clarity of parameters, but the API calls are C++.

// Placeholder for MblMwLedPattern struct definition and initialization
// struct MblMwLedPattern {
//     uint8_t high_intensity;
//     uint8_t low_intensity;
//     uint16_t rise_time_ms;
//     uint16_t high_time_ms;
//     uint16_t fall_time_ms;
//     uint16_t pulse_duration_ms;
//     uint16_t delay_time_ms;
//     uint8_t repeat_count;
// };

// Example initialization (conceptual, actual C++ might differ)
// MblMwLedPattern pattern;
// pattern.high_intensity = 31;
// pattern.low_intensity = 31;
// pattern.rise_time_ms = 0;
// pattern.high_time_ms = 2000;
// pattern.fall_time_ms = 0;
// pattern.pulse_duration_ms = 2000;
// pattern.delay_time_ms = 0;
// pattern.repeat_count = UINT8_MAX; // Represents 0xFF

// Assuming 'device.board' is a pointer to the board and 'color' is a valid color value
// mbl_mw_led_stop_and_clear(device.board);
// mbl_mw_led_write_pattern(device.board, &pattern, color);
// mbl_mw_led_play(device.board);

// Start playing the programmed patterns
// mbl_mw_led_play(board);

// To stop and clear patterns:
// mbl_mw_led_stop_and_clear(board);

```

--------------------------------

### MetaWear Board Connection Management

Source: https://mbientlab.com/iosdocs/latest/_sources/metawearboard.rst

Manages the Bluetooth LE connection to the MetaWear board. `connectAndSetup` establishes the connection and initializes the board's state. `cancelConnection` closes the connection and can cancel pending connection attempts. The task returned by `connectAndSetup` completes when the device disconnects.

```APIDOC
MetaWear.connectAndSetup() -> Task<Void>
  - Connects to the MetaWear board and initializes its state.
  - Returns: A Task that completes when the connection is established and the board is initialized.
  - Continuation: Handles connection success, cancellation, or errors.
  - Example:
    device.connectAndSetup().continueWith { t in
        if t.isCancelled {
            print("cancelConnection() called before connection completed")
        } else if t.isFaulted {
            print("Connection Error: \(t.error?.localizedDescription ?? \"N/A\")")
        } else {
            print("Connection Success")
        }
    }

MetaWear.cancelConnection() -> Task<Void>
  - Closes the Bluetooth LE connection to the board.
  - If a `connectAndSetup` task is pending, it will be cancelled.
  - Returns: A Task that completes when the connection is closed.
  - Example:
    device.cancelConnection().continueWith { t in
        print("Disconnected")
    }

Watching for Disconnects:
  - The task returned from `connectAndSetup` will complete when the device disconnects.
  - Example:
    device.connectAndSetup().continueWith { t in
        t.result?.continueWith { t in
            print("Lost connection")
        }
    }
```
Tokens:
Raw