feat: Add platform services

Author: Soap-141

DeviceCore.sln

@@ -0,0 +1,60 @@
+
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 17
+VisualStudioVersion = 17.14.36301.6
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "lib", "lib", "{02EA681E-C7D8-13C7-8484-4AC65E1B71E8}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "app", "app", "{AD02B423-808C-484C-B74C-8BD7D1A4A6F8}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DeviceCore.Abstractions", "src\lib\DeviceCore.Abstractions\DeviceCore.Abstractions.csproj", "{26E9BF70-760F-DFCB-CBD5-E521C59D98FD}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DeviceCore.Uno.WinUI", "src\lib\DeviceCore.Uno.WinUI\DeviceCore.Uno.WinUI.csproj", "{D1516BF4-7E73-CC38-0C50-ABF8C0B4F447}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "build", "build", "{FA423D9C-B957-4517-9D09-0BF8E8991008}"
+	ProjectSection(SolutionItems) = preProject
+		build\azure-pipelines.yml = build\azure-pipelines.yml
+		build\gitversion.yml = build\gitversion.yml
+		build\stage-build.yml = build\stage-build.yml
+		build\stage-release.yml = build\stage-release.yml
+	EndProjectSection
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "root", "root", "{FD0DD8AF-C1A2-4FB4-9FE3-D039FA20D310}"
+	ProjectSection(SolutionItems) = preProject
+		.gitignore = .gitignore
+		.mergify.yml = .mergify.yml
+		BREAKING_CHANGES.md = BREAKING_CHANGES.md
+		CODE_OF_CONDUCT.md = CODE_OF_CONDUCT.md
+		CONTRIBUTING.md = CONTRIBUTING.md
+		LICENSE = LICENSE
+		README.md = README.md
+	EndProjectSection
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "doc", "doc", "{DCAB9D57-69DC-4C5D-8703-43C374CB0387}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Any CPU = Debug|Any CPU
+		Release|Any CPU = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{26E9BF70-760F-DFCB-CBD5-E521C59D98FD}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{26E9BF70-760F-DFCB-CBD5-E521C59D98FD}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{26E9BF70-760F-DFCB-CBD5-E521C59D98FD}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{26E9BF70-760F-DFCB-CBD5-E521C59D98FD}.Release|Any CPU.Build.0 = Release|Any CPU
+		{D1516BF4-7E73-CC38-0C50-ABF8C0B4F447}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{D1516BF4-7E73-CC38-0C50-ABF8C0B4F447}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{D1516BF4-7E73-CC38-0C50-ABF8C0B4F447}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{D1516BF4-7E73-CC38-0C50-ABF8C0B4F447}.Release|Any CPU.Build.0 = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+	GlobalSection(NestedProjects) = preSolution
+		{26E9BF70-760F-DFCB-CBD5-E521C59D98FD} = {02EA681E-C7D8-13C7-8484-4AC65E1B71E8}
+		{D1516BF4-7E73-CC38-0C50-ABF8C0B4F447} = {02EA681E-C7D8-13C7-8484-4AC65E1B71E8}
+	EndGlobalSection
+	GlobalSection(ExtensibilityGlobals) = postSolution
+		SolutionGuid = {483215CF-95DE-4CCF-A682-832BB70A63F4}
+	EndGlobalSection
+EndGlobal

README.md

@@ -1,39 +1,116 @@
-# Open Source Project Template
+# Device Core
 
-This repository contains a template to seed a repository for an Open Source
-project.
+{Project tag line}
 
-## How to use this template
+{Small description of the purpose of the project}
 
-1. Check out this repository
-2. Delete the `.git` folder
-3. Git init this repository and start working on your project!
-4. Prior to submitting your request for publication, make sure to review the
-   [Open Source guidelines for publications](https://nventive.visualstudio.com/Internal/_wiki/wikis/Internal_wiki?wikiVersion=GBwikiMaster&pagePath=%2FOpen%20Source%2FPublishing&pageId=7120).
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 
-## Features (to keep as-is, configure or remove)
-- [Mergify](https://mergify.io/) is configured. You can edit or remove [.mergify.yml](/.mergify.yml).
+## Getting Started
 
-The following is the template for the final README.md file:
+1. Add the `DeviceCore.Uno.WinUI` NuGet package to your projects (Windows, Android and iOS).
+   > 💡 If you need to implement more platforms or create custom implementations, you can use the `DeviceCore.Abstractions` NuGet package.
 
----
+1. Create an instance of any service. We'll cover dependency injection in details later on in this documentation.
 
-# Project Title
+   ```cs
+   using DeviceCore;
 
-{Project tag line}
+   var flashlightService = new FlashlightService();
+   ```
 
-{Small description of the purpose of the project}
+1. Use the service.
 
-[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+   ```cs
+   flashlightService.Brightness = 0.5f;
+   flashlightService.Toggle();
+   ```
 
-## Getting Started
+## Next Step
+
+### Using Dependency Injection
+
+Here is a simple code that does dependency injection using `Microsoft.Extensions.DependencyInjection` and `Microsoft.Extensions.Hosting`.
 
-{Instructions to quickly get started using the project: pre-requisites, packages
-to install, sample code, etc.}
+```cs
+using DeviceCore;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+
+var host = new HostBuilder()
+   .ConfigureServices(serviceCollection => serviceCollection
+      .AddSingleton(_ => DispatcherQueue.GetForCurrentThread())
+      .AddSingleton<IAccelerometerService, AccelerometerService>()
+      .AddSingleton<IAmbientLightProvider, AmbientLightProvider>()
+      .AddSingleton<IBatteryInformationProvider, BatteryInformationProvider>()
+      .AddSingleton<IFlashlightService, FlashlightService>()
+      .AddSingleton<IScreenWakeLockService, ScreenWakeLockService>()
+   )
+   .Build();
+```
 
 ## Features
 
-{More details/listing of features of the project}
+Now that everything is setup, Let's see what else we can do!
+
+### Accelerometer
+
+The `AccelerometerService` provides access to the device's accelerometer sensor, allowing you to read acceleration data in three dimensions (X, Y, Z).
+
+> 💡 The `ObserveAcceleration` and `ObserveDeviceShaken` methods and will return an observable yielding `null` on devices that do not support `Accelerometer` or devices that do not have such a sensor.
+
+> 💡 Unsubscribe from the `ObserveAcceleration` and `ObserveDeviceShaken` observables when you no longer need the readings to avoid unnecessary battery consumption.
+
+> 💡 On iOS features built-in shake gesture recognition. Android use a common implementation to approximate shake detection. You can implement custom shake detection using the `ObserveAcceleration` method if needed.
+
+> 💡 On Android, if both `ObserveAcceleration` and `ObserveDeviceShaken` observables are used and `ReportInterval` is set high, they may be yielding reading more often than requested due to multiple subscribers.
+
+### Light Sensor
+
+The `AmbientLightProvider` provides access to the device's ambient light sensor, allowing you to read the current light level.
+
+> 💡 The `ObserveCurrentReading` method and will return an observable yielding `null` on devices that do not support `Accelerometer`, on devices that do not have such a sensor, or on iOS.
+
+> 💡 Unsubscribe from the `ObserveCurrentReading` observable when you no longer need the readings to avoid unnecessary battery consumption.
+
+### Battery Information
+
+The `BatteryInformationProvider` provides access to the device's battery information, allowing you to read the current battery level and status.
+
+> 💡 On Android, the `GetAndObserveRemainingChargePercent` observable is not updated continuously as there is no API that provides such events. It is triggered by system `Low` and `Ok` battery state broadcasts only. The `RemainingChargePercent` property always returns the up-to-date value. For continuous monitoring you can set up periodic polling.
+
+#### Android
+
+To use the battery information on Android, ensure you have the correct permissions in your `AndroidManifest.xml`.
+
+```xml
+<uses-permission android:name="android.permission.BATTERY_STATS" />
+```
+
+### Flashlight
+
+The `FlashlightService` allows you to turn the phone's camera flashlight on and off.
+
+> 💡 On Android, flashlight brightness cannot be controlled, hence any non-zero brightness level results in the full brightness of the flashlight.
+
+> 💡 On iOS, in case the device supports the torch, brightness level is fully supported. In case the device has only flash, any non-zero brightness level will result in the full brightness of the flashlight.
+
+#### Android
+
+To use the flashlight on Android, ensure you have the correct permissions in your `AndroidManifest.xml`.
+
+```xml
+<uses-permission android:name="android.permission.FLASHLIGHT" />
+<uses-permission android:name="android.permission.CAMERA" />
+```
+
+### Keeping Screen On
+
+To enables an application to request to keep the device's screen on, use the `ScreenWakeLockService`.
+
+## Acknowledgements
+
+Take a look at [Uno.WinRT](https://platform.uno/docs/articles/features/using-winrt.html) that we use for the mobile platforms implementation.
 
 ## Breaking Changes
 

src/lib/DeviceCore.Abstractions/Accelerometer/AccelerometerReading.cs

@@ -0,0 +1,50 @@
+using System;
+using System.Collections.Generic;
+
+namespace DeviceCore;
+
+/// <summary>
+/// Represents an accelerometer reading.
+/// </summary>
+public sealed class AccelerometerReading
+{
+	public AccelerometerReading(double accelerationX, double accelerationY, double accelerationZ, TimeSpan? performanceCount, DateTimeOffset timestamp)
+	{
+		AccelerationX = accelerationX;
+		AccelerationY = accelerationY;
+		AccelerationZ = accelerationZ;
+		PerformanceCount = performanceCount;
+		Timestamp = timestamp;
+	}
+
+	/// <summary>
+	/// Gets the g-force acceleration along the x-axis.
+	/// </summary>
+	public double AccelerationX { get; }
+
+	/// <summary>
+	/// Gets the g-force acceleration along the y-axis.
+	/// </summary>
+	public double AccelerationY { get; }
+
+	/// <summary>
+	/// Gets the g-force acceleration along the z-axis.
+	/// </summary>
+	public double AccelerationZ { get; }
+
+	/// <summary>
+	/// Gets the performance count associated with the reading.
+	/// This allows the reading to be synchronized with other devices and processes on the system.
+	/// </summary>
+	public TimeSpan? PerformanceCount { get; }
+
+	/// <summary>
+	/// Gets the data properties reported by the sensor.
+	/// </summary>
+	public IReadOnlyDictionary<string, object>? Properties { get; }
+
+	/// <summary>
+	/// Gets the time at which the sensor reported the reading.
+	/// </summary>
+	public DateTimeOffset Timestamp { get; }
+}

src/lib/DeviceCore.Abstractions/Accelerometer/FakeAccelerometerService.cs

@@ -0,0 +1,25 @@
+using System;
+using System.Reactive.Linq;
+
+namespace DeviceCore;
+
+/// <summary>
+/// The fake implementation of <see cref="IAccelerometerService"/> for testing purposes.
+/// </summary>
+public sealed class FakeAccelerometerService : IAccelerometerService
+{
+	/// <inheritdoc/>
+	public uint ReportInterval { get; set; }
+
+	/// <inheritdoc/>
+	public IObservable<AccelerometerReading?> ObserveAcceleration()
+	{
+		return Observable.Return<AccelerometerReading?>(new AccelerometerReading(0d, 0d, 0d, null, DateTimeOffset.Now));
+	}
+
+	/// <inheritdoc/>
+	public IObservable<DateTimeOffset?> ObserveDeviceShaken()
+	{
+		return Observable.Return<DateTimeOffset?>(DateTimeOffset.Now);
+	}
+}

src/lib/DeviceCore.Abstractions/Accelerometer/IAccelerometerService.cs

@@ -0,0 +1,36 @@
+using System;
+
+namespace DeviceCore;
+
+/// <summary>
+/// Provides functionality to observe accelerometer readings and detect device shake events.
+/// </summary>
+/// <remarks>
+/// On Android, when both ReadingChanged and Shaken events are attached and the user sets the ReportInterval to a high value, the ReadingChanged event may be raised more often than requested.
+/// This is because for multiple subscribers to the same sensor, the system may raise the sensor events with the frequency of the one with the lowest requested report delay.
+/// This is, however, in line with the behavior of the WinUI Accelerometer, and you can filter the events as necessary for your use case.
+/// </remarks>
+public interface IAccelerometerService
+{
+	/// <summary>
+	/// Gets or sets the current report interval for the accelerometer.
+	/// </summary>
+	uint ReportInterval { get; set; }
+
+	/// <summary>
+	/// Observes the acceleration data from the device's accelerometer.
+	/// </summary>
+	/// <remarks>
+	/// If the device does not support an accelerometer sensor, this method will return an observable sequence that yields null.
+	/// </remarks>
+	IObservable<AccelerometerReading?> ObserveAcceleration();
+
+	/// <summary>
+	/// Observes when the device is shaken.
+	/// </summary>
+	/// <remarks>
+	/// If the device does not support an accelerometer sensor, this method will return an observable sequence that yields null.
+	/// </remarks>
+	/// <returns>An observable sequence yielding a timestamp when the device has been shaken.</returns>
+	IObservable<DateTimeOffset?> ObserveDeviceShaken();
+}

src/lib/DeviceCore.Abstractions/AmbientLight/AmbiantLightReading.cs

@@ -0,0 +1,43 @@
+using System;
+using System.Collections.Generic;
+
+namespace DeviceCore;
+
+/// <summary>
+/// Represents an ambient light–sensor reading.
+/// </summary>
+public sealed class AmbiantLightReading
+{
+	public AmbiantLightReading(
+		float illuminanceInLux,
+		TimeSpan? performanceCount,
+		IReadOnlyDictionary<string, object>? properties,
+		DateTimeOffset timestamp
+	)
+	{
+		IlluminanceInLux = illuminanceInLux;
+		PerformanceCount = performanceCount;
+		Properties = properties;
+		Timestamp = timestamp;
+	}
+
+	/// <summary>
+	/// Gets the illuminance level in lux.
+	/// </summary>
+	public float IlluminanceInLux { get; }
+
+	/// <summary>
+	/// Gets the performance count associated with the reading.This allows the reading to be synchronized with other devices and processes on the system.
+	/// </summary>
+	public TimeSpan? PerformanceCount { get; }
+
+	/// <summary>
+	/// Gets the data properties reported by the sensor.
+	/// </summary>
+	public IReadOnlyDictionary<string, object>? Properties { get; }
+
+	/// <summary>
+	/// Gets the time at which the sensor reported the reading.
+	/// </summary>
+	public DateTimeOffset Timestamp { get; }
+}

src/lib/DeviceCore.Abstractions/AmbientLight/FakeAmbientLightProvider.cs

@@ -0,0 +1,16 @@
+using System;
+using System.Reactive.Linq;
+
+namespace DeviceCore;
+
+/// <summary>
+/// The fake implementation of <see cref="IAmbientLightProvider"/> for testing purposes.
+/// </summary>
+public sealed class FakeAmbientLightProvider : IAmbientLightProvider
+{
+	/// <inheritdoc/>
+	public IObservable<AmbiantLightReading?> ObserveCurrentReading()
+	{
+		return Observable.Return(new AmbiantLightReading(0f, null, null, DateTimeOffset.Now));
+	}
+}

src/lib/DeviceCore.Abstractions/AmbientLight/IAmbientLightProvider.cs

@@ -0,0 +1,21 @@
+using System;
+
+namespace DeviceCore;
+
+/// <summary>
+/// Provides access to the current ambient light (illuminance level) reading in lux and detects changes.
+/// </summary>
+/// <remarks>
+/// The device or emulator that you're using must support an ambient light sensor.
+/// </remarks>
+public interface IAmbientLightProvider
+{
+	/// <summary>
+	/// Observes the current ambient light reading.
+	/// </summary>
+	/// <remarks>
+	/// If the device does not support an ambient light sensor, this method will return an observable sequence that yields null.
+	/// </remarks>
+	/// <returns>An observable sequence yielding the current ambient light reading.</returns>
+	IObservable<AmbiantLightReading?> ObserveCurrentReading();
+}