• Make Library nullable
• Utilize data classes / records
• Update regards pattern matching
  • is null / is not null
• Activate .NET 5 SDK Code Analyzers
• Remove unnecessary usings

Source code at undera/pylgbst under MIT license

• Move HubAlert.cs to Enum folder and change namespace to SharpBrick.PoweredUp (as it is exposed from now on)
• Extend Hub.cs
• Create an observable property of type IObservable<HubAlert>.
• Wire the new observable property with the existing UpstreamMessages and filter only HubAlertMessage.

• Dual build for .NET Core 3.1 and .NET 5 then
• Change NuGet dependency from "Contracts" to "SDK"

dotnet/docs#18875

• Define as .NET Core Global Tool
• Correct project name
• Move to src folder
• Make command line argument parsing a proper experience
• More Advertisement in the README

Fi missing capability of #36

Usage e.g.

await motor.StartSpeedAsync(CCW * 75);

If CCW and CW are not consistent in regards of usage across modes and devices, consider using a pattern similar to XNamespace.

Lesson learnt from #47

• Extract string representation from message-trace app
• Add string representation to PoweredUpMessage.ToString() method
• Add function to hookup with protocol for tracing

The SPIKE Prime Hub can recognize taps on the device. Maybe also the TechnicMediumHub since it exposes the internal device.

Large list of trains/big installations may not be interested in the hubs.

When you build a user interface or something related, you expect the connected sensors, actors and hubs to follow a pre-defined model (which you then control by your UI).

var model = new DeploymentModelBuilder()
                 .AddHub<TechnicMediumHub>(hubBuilder => hubBuilder
                     .AddDevice<TechnicLinearMotor>(hub => hub.A)
                     .AddDevice<TechnicXlargeLinearMotor>()
                 )
                .Build();

var errors = model.Verify(protocol);

// or reactive

var errorObservable = protocol.VerifyObservable(model);

With errors being something like ..

class DeploymentError
{
    int ErrorCode;
    byte HubId;
    byte? PortId;
    string Message;
}

Source code under virantha/bricknil licensed Apache-2.0

• PortValue and PortCombinedValue are encoding their payload data according to definitions set-up in PortInputFormat(Combined)Setup requests. As a result, the protocol decoder itself is stateful.
  • Port Knowledge has to be present already on the Protocol Level and not the Hub/Device Logic Models
  • The Protocol will need middlewares which can maintain the knowledge, irrelevant of the uses of the protocol
  • Since querying all many properties (PortInformation, PortModeInformation) take significant time and their properties are static by device type, hardcoded caching by device type/fw/hw is possible. An explicit discovery mode for unknown devices can be implemented as a "business function".
  • The remaining informaton (HubAttachedIO Attach/Detach, PortInputFormat) are user choices (in physical doing or software), their input is dynamic and needs implementation as middlewares.

Involved Messages

• HubAttachedIOMessage (event Attached): existence and device type.

• HubAttachedIOMessage (event Detached): removal of existence, port knowledge reset.

• PortInputFormatSingleMessage: format description of the PortValueSingleMessage.

• PortInputFormatCombinedModeMessage: format description of the PortValueCombinedModeMessage.

• PortInformationMessage (mode info + mode combinations): basic device description (cachable).

• PortModeInformationMessage (~10 properties): device property description (cachable).

Architecture Changes:

• Establishment of a Knowledge Model SharpBrick.PoweredUp.Knowledge.
• No introduction of a middleware stack in PoweredUPProtocol. Not yet needed.
• Protocol function to lookup up knowledge.
• Protocol function to update knowledge.
• Business Function DiscoverPorts which acts on top of the PoweredUpProtocol but can access the knowledge

Needs

• Hub and Devices need to consume the same PowerdUpProtocol with its two methods ReceiveMessageAsync (which is directly bound through to the BT stack) and SendMessageAsync. Multiple subscriptions are needed.
• Devices are attached/detached dynamically creating the need for new pipelines
• Devices should receive a filtered set of messages (no need for them to read the messages of other devices)
• There are pipes in/out with correlation events occurring

Libraries

• System.Reactive

  • push based
  • Does not work well with general purpose async/await behaviors => NO SHOW
  • buffering complicated
  • LINQ
  • Good subscription management
  • Can build pipelines dynamically on demand
  • Not Span capable

• violetgrass/middleware

  • push based
  • async/await
  • No buffering
  • No LINQ
  • Exposes middleware pattern
  • Might be Span capable (if done right; cross checked with library)
  • Cannot branch dynamically => NEEDS extensions
  • No subscription management

• IAsyncEnumerable / System.Linq.Async

  • pull based not pushed based => NO SHOW
  • LINQ

• System.Threading.Channels

  • push based
  • buffering is available
  • No LINQ
  • needs an active consumer (a thread awaiting something) => that would not be reasonable on all devices when just updating properties => NO SHOW
  • Is used in kestrel e.g. for Quic packages

Decision & Rationale

?

• Configure a ServiceCollection with logging
• Add support for --trace option and adjust logging level by it
• Add tracer to protocol setup
• Add serviceProvider to hub and loggerfactory to WinRT adapter.
• Move message-trace sample content (rgb, input, motor) into a mixed bag example
• Deprecate message-trace project

Source code under corneliusmunz/legoino under MIT license

MIT licensed source code, found here

• Rename existing SharpBrick.PoweredUp.Hub into BaseHub
• Add TwoPortHub (88009) like TechnicMediumHub

Note: Note to everyone: I do not have the hardware and have in the foreseeable future no interest in purchasing them. If you want support for this hardware in this library, please contribute. I will guide you through the process and assist with everything needed.

• See what the smart people at nathankellenicki/node-poweredup#97 are doing
• Analyze Port (Mode) Information what constraints to apply => nothing useful

Use Cases

• Implement fallback device for unknown devices (flag)
• Implement fallback for known but not implemented devices (flag)
• Use DynamicDevice.Discover in case GetStaticPortInformation does not have any information for typed device (aka. soft react to firmware updates).

Strategy

• Create a sub class DynamicDevice which derives from Device
• Add a discovery function as DynamicDevice.DiscoverAsync. Decision needed whether we auto-call it when discovered by HubAttachedIOMessage or by user before usage by user (since pretty expensive).
• Add ConcurrentDictionary<byte,Mode> Modes to Device which is auto populated on Discovery (or on auto-playing knowledge into the device) ... so for existing devies these are auto-populated.
• Add default observables, properties (SI, Raw, Pct) and WriteDirectMode method to Mode
• Rewrite existing invocations to target Mode.

Should be non-breaking at the API surface.

A motor has a limited api. Default control models for usage as wheel, tank-like steering, or speed sliders, gears etc.

During Intialization

• Hub Properties (await all)
• Known Devices
• Observable for device changes (after protocol knowledge update)

Support

• DeploymentVerfication achieved (#36)

Source code at nathankellenicki/node-poweredup under MIT license

Enable the usage of the SharpBrick.PoweredUp library in Blazor on WebAssembly. For that a bridge between Blazor and WebBluetooth is required. After the bridge, an adapter to the SharpBrick.PoweredUp.Bluetooth interface is required.

• Active Connection == own Scope
  • Create Scope in host during hub/protocol initialization
• Move the following types to a AddScoped lifetime
  • BluetoothKernel (remove bluetoothAddress from constructor and move to ConnectAsync)
  • PoweredUpProtocol (add deviceFactory as a constructor argument and remove IServiceProvider service locator trap)
  • Rewrite DeviceFactory/HubFactory to use Transient types in the IServiceProvider. OPEN QUESTION: How to handle hubId and portId in an elegant way
  • Add constructor argument deviceFactory to hub.
• Add interface to PoweredUpHost to wire up a protocol

non-breaking in theory

A model mimicking the physical hub

• Reading DEG
• Reading IMP
• Configuration (impact, orientation)
• Do not implement factory reset

Generally the library is not supporting multiple HubIds over the same bluetooth device/service/gatt profile.

• CommonMessageHeaderEncoder.Encode hardcoded 0x00
• Most Hubs, Devices do not encode their hub id into the commands
• Host/Hubs need to recognize their associated HubId

... Many more issues

Knowledge dump

• TachoMotor.StartSpeedForDegreesAsync support moving the motor by degrees. It operates relative of its current position.
• AbsoluteMotor.GotoAbsolutePositionAsync allows moving the motor to an absolute position. It operates relative to a changeable zero position.
• The input mode 2 (POS) is reflecting the position relative to a changeable zero position (firmware in-memory encoded)
• The input mode 3 (APOS) is reflecting the position relative to marked zero position (physically encoded).
• POS is resetable with PortOutputCommandPresetEncoderMessage, APOS not.
• Technic(X)LargeLinearMotor / TechnicMediumHub do not remember their zero POS position.

Implementation

• Encode PortOutputCommandPresetEncoderMessage
• Add a AbsoluteMotor.GotoRealZeroAsync which moves the motor to align the position and the absolute position.
• Add a TachoMotor.SetZeroAsync allowing to reseting the zero value to the current position.
• Add comments to GotoAbsolutePosition and AbsolutePosition(Observable) explaining the behavior.

• Intention: Consumers should not need to search namespaces to discover an API
• Solution:
  • Break namespace / folder alignment (e.g. sub folder Devices/Hubs despite all being in root namespace)
  • Move re-used types (mainly enums from Messages / Devices into the root namespace with separate folder Enums)
• Rationale: Consumer usability is more important than code organization

• Enum according to .NET Guidelines (flags plural, all other singular)
• Enums of messages into global namespace (since also used by Functions, Devices, ..)
• unit clarifications of all parameters (e.g. timeInMs)
• remove abbreviations
• add documentation
• cleanup namespaces to allow regular users to only include one namespace
  • Remove Devices and Hub Namespace
  • Move Knowledge back into Protocol namespace
  • Move shared usage enums into root namespace

Check if already supported by PowerdUpHost.Find<THub>(ulong bluetoothAddress) (w/ or w/o discovery)

Feature found in #47.

When designing a model we want to ensure that a hub and devices are correctly connected. Model to verify the correct connections.

• Use code sample from message-trace and productize it
• Expose a function Device.CheckCombinedModeSupport to test mode combinations on devices and return a valid combination mode index (so of the array of possible combinations, find the position which is closest to the requested set). Rationale over constants exposing supported combinations on types: An implementer might use an abstract parent type like AbsoluteMotor where valid combinations would need to be explicitly tested.

Design

Task<bool> Device.TryLockDeviceForCombinedModeNotificationSetupAsync(params byte[] modeIndices);
Task Device.SetupNotificationAsync(byte modeIndex, bool enabled, ulong deltaInterval);
Task Device.UnlockFromCombinedModeNotificationSetupAsync(bool enableUpdates);

Brain Teaser ;)

Devices exposes supported combination of modes (X) as an array. These combined modes (X) are the only possible ones from the hardware but the user can restrict to a subset of modes (Y) from a given supported combination mode ones (X). When activating a supported combination (X) from by using the index (Z) in the array (X). After the initial selection of the combined mode using the index (Z) and additional selection of modes (W), the user can now format a subset of the modes (Y).

When decoding the Input, the decoder needs to know selected modes (Y). However, the upstreamed value is bit pointered to the array of active mode/dataset (W).

@Mattze0815 fyi

• check usage of WinRT on netstandard2.0
• check usage of Span<T> on netstandard2.0
• check compiling C# 8.0 feature usage

vs: This is a hobby project and I want to use C# x and .NET y features

Lesson Learnt from #47

• Allow Combined Modes
• Input/Output usage
• Check synchronizable for Virtual Ports
• Check other guards from Vouzamo/Lego

Lesson learnt from #47

Calibration, device discovery, easing, etc are functions applied on a hub or a device, temporarily or permanently. Find the best model.

• Check for layering ideas
• Check for supported devices types
• Check for legacy / old device compatibility

Source Code (MIT licensed)

Typically a command is send out (which is an async operation) and then confirmed by the device with an incoming message.

Currently most operations are executing just the initial send operation and leave the API users with the synchronization effort for awaiting the response.