add comments to clarify Overlay and Merge method; add first draft docs

docs/diagrams/src/models-class.puml

@@ -0,0 +1,64 @@
+@startuml
+!include https://raw.githubusercontent.com/joekolodz/puml-themes/main/themes/sierrahotas/puml-theme-sierrahotas.puml
+
+title 
+
+SierraHOTAS
+Class Diagram
+
+Models
+
+end title
+
+interface IHOTASBaseMap
+
+class HOTASCollection {
+    + <<event>> KeystrokeDownSent
+    + <<event>> KeystrokeUpSent
+    + <<event>> MacroStarted
+    + <<event>> MacroCancelled
+    + <<event>> ButtonPressed
+    + <<event>> AxisChanged
+    + <<event>> ModeProfileChanged
+    + <<event>> LostConnectionToDevice
+}
+
+class HOTASDevice
+class "ButtonMap\nCollection" as ButtonMap
+class HOTASQueue {
+    read loop
+}
+
+class Joystick {
+    (DirectInput)
+}
+class HOTASAxis
+class HOTASButton
+class "Forward Button Map" as ForwardButtonMap
+class "Reverse Button Map" as ReverseButtonMap
+class Segments
+class ActionCatalogItem
+class ButtonAction {
+    scan codes
+    flags
+    etc
+}
+
+IHOTASBaseMap .right. ButtonMap
+
+HOTASCollection -- "0..*" HOTASDevice
+HOTASDevice -- "0..*" ButtonMap
+HOTASDevice -- "1"  HOTASQueue
+HOTASDevice -- "1" Joystick
+
+ButtonMap -- "0..*" HOTASAxis
+ButtonMap -- "0..*" HOTASButton
+
+HOTASAxis -- "0..*" Segments
+HOTASAxis -- "0..*" ForwardButtonMap
+HOTASAxis -- "0..*" ReverseButtonMap
+
+HOTASButton -- ActionCatalogItem
+ActionCatalogItem -- "0..*" ButtonAction
+
+@enduml

docs/diagrams/src/models-component.puml

@@ -0,0 +1,65 @@
+@startuml
+
+!theme bluegray
+
+skinparam linetype ortho
+skinparam roundcorner 6
+
+skinparam rectangle{
+    bordercolor black
+}
+
+skinparam collections{
+    bordercolor black
+}
+
+skinparam note{
+    fontsize 9
+    BackgroundColor $PRIMARY-$PRIMARY_LIGHT
+}
+
+rectangle HOTASCollection
+collections HOTASDevice
+collections "ButtonMap\n(IHotasBaseMap)" as ButtonMap
+rectangle "HOTASQueue\n(read loop)" as HOTASQueue
+rectangle "Joystick\n(DirectInput)" as Joystick
+collections HOTASAxis
+collections "Button Map" as HOTASButton
+collections "Reverse Button Map" as ReverseButtonMap
+collections Segments
+
+note right of HOTASCollection
+KeystrokeDownSent
+KeystrokeUpSent
+MacroStarted
+MacroCancelled
+ButtonPressed
+AxisChanged
+ModeProfileChanged
+endnote
+
+
+note right of HOTASDevice
+KeystrokeDownSent
+KeystrokeUpSent
+MacroStarted
+MacroCancelled
+ButtonPressed
+AxisChanged
+ModeProfileSelected
+ShiftReleased
+
+endnote
+
+
+HOTASCollection --> HOTASDevice
+HOTASDevice --> ButtonMap
+HOTASDevice --> HOTASQueue
+HOTASDevice --> Joystick
+ButtonMap ..> HOTASAxis
+ButtonMap .left.> HOTASButton
+HOTASAxis --> HOTASButton
+HOTASAxis --> ReverseButtonMap
+HOTASAxis --> Segments
+
+@enduml

docs/diagrams/src/sequence.puml

@@ -0,0 +1,112 @@
+@startuml
+!include https://raw.githubusercontent.com/joekolodz/puml-themes/main/themes/sierrahotas/puml-theme-sierrahotas.puml
+
+!$BLACK = "#000"
+
+!$TEXT_SECONDARY = $BLACK
+
+skinparam sequence {
+	BorderColor $OBJECT_BORDER
+	' For some reason sequence title font color does not pick up from global
+	TitleFontColor $TEXT
+	BackgroundColor $OBJECT_BACKGROUND
+	StartColor $PRIMARY
+	EndColor $PRIMARY
+	''
+	BoxBackgroundColor $BGCOLOR
+	BoxBorderColor $GRAY
+	BoxFontColor $DARK
+	''
+	DelayFontColor $DARK
+	''
+	LifeLineBorderColor $TEXT
+	LifeLineBorderThickness 2
+	LifeLineBackgroundColor $OBJECT_BACKGROUND
+	''
+	GroupBorderColor $OBJECT_BORDER
+	GroupFontColor $TEXT
+	GroupHeaderFontColor $TEXT_HEADER
+	GroupBackgroundColor $HEADER_BACKGROUND
+	GroupBodyBackgroundColor $OBJECT_BACKGROUND
+	GroupHeaderBackgroundColor $BACKGROUND
+	''
+	DividerBackgroundColor $OBJECT_BACKGROUND
+    DividerBorderColor $OBJECT_BORDER
+    DividerBorderThickness 2
+    DividerFontColor $GOLD
+	''
+	ReferenceBackgroundColor $OBJECT_BACKGROUND
+	ReferenceBorderColor $OBJECT_BORDER
+	ReferenceFontColor $DARK_BLUEGRAY
+	ReferenceHeaderFontColor $TEXT_HEADER
+	''
+	StereotypeFontColor $TEXT
+
+	AttributeFontColor $TEXT
+	AttributeFontSize 50
+
+}
+
+
+
+skinparam note{
+    FontColor $TEXT_SECONDARY
+}
+
+
+title 
+
+SierraHOTAS
+Sequence Diagram
+
+Models
+
+end title
+
+participant Participant as Foo
+actor       Actor       as Foo1
+boundary    Boundary    as Foo2
+control     Control     as Foo3
+entity      Entity      as Foo4
+database    Database    as Foo5
+collections Collections as Foo6
+queue       Queue       as Foo7
+Foo -> Foo1 : To actor 
+Foo -> Foo2 : To boundary
+Foo -> Foo3 : To control
+Foo -> Foo4 : To entity
+Foo -> Foo5 : To database
+Foo -> Foo6 : To collections
+Foo -> Foo7: To queue
+
+participant "Famous Bob" as Bob << Generated >>
+participant Alice << (C,$GOLD) Testable >>
+
+Alice -> Bob: Authentication Request
+
+alt successful case
+
+    Bob -> Alice: Authentication Accepted
+rnote left: this is a first note
+else some kind of failure
+
+    Bob -> Alice: Authentication Failure
+    group My own label
+    Alice -> Log : Log attack start
+        loop 1000 times
+            Alice -> Bob: DNS Attack
+        end
+    Alice -> Log : Log attack end
+    end
+
+else Another type of failure
+
+   Bob -> Alice: Please repeat
+
+end
+
+
+
+
+Bob->Alice: First message
+@enduml

src/App.xaml

@@ -20,7 +20,7 @@
         <SolidColorBrush x:Key="SelectedBrush" Color="#2f4c5a" />
         <SolidColorBrush x:Key="SelectedBorderBrush" Color="#26a0da" />
 
-        <SolidColorBrush x:Key="GroupBorderBrush" Color="#708090" />
+        <SolidColorBrush x:Key="GroupBorderBrush" Color="SlateGray" />
         <SolidColorBrush x:Key="NormalBorderBrush" Color="Azure" />
         <SolidColorBrush x:Key="RowBrush" Color="Transparent" />
         <SolidColorBrush x:Key="RowAlternateBrush" Color="#424242" />

src/Models/HOTASDevice.cs

@@ -251,6 +251,10 @@ private void RemoveQueueHandlers()
             _hotasQueue.LostConnectionToDevice -= OnLostConnectionToDevice;
         }
 
+        /// <summary>
+        /// Existing buttons in the profile will overlay buttons on the device. If a device has a button with matching profile, then we'll keep that button (otherwise we'd lose it if we just took profile buttons)
+        /// This allows a device to change without losing mappings (for instance when chaining a new Virpil device, or manually editing and removing buttons from the profile's JSON file)
+        /// </summary>
         public void OverlayAllProfilesToDevice()
         {
             var mergedModeProfiles = new Dictionary<int, ObservableCollection<IHotasBaseMap>>();
@@ -267,6 +271,12 @@ public void OverlayAllProfilesToDevice()
             _hotasQueue.SetModeProfiles(ModeProfiles);
         }
 
+        /// <summary>
+        /// Examine each button in the Source map. If that button is also found in the Destination map, then use the Destination map's button, otherwise use the Source map's button.
+        /// </summary>
+        /// <param name="sourceMap"></param>
+        /// <param name="destinationMap"></param>
+        /// <returns></returns>
         private ObservableCollection<IHotasBaseMap> MergeMaps(ObservableCollection<IHotasBaseMap> sourceMap, ObservableCollection<IHotasBaseMap> destinationMap)
         {
             var merged = new ObservableCollection<IHotasBaseMap>();

src/ViewModels/DeviceViewModel.cs

@@ -6,7 +6,7 @@
 using System.ComponentModel;
 using System.Linq;
 using System.Runtime.CompilerServices;
-using System.Windows.Threading;
+using SierraHOTAS.Controls;
 using SierraHOTAS.Factories;
 
 namespace SierraHOTAS.ViewModels