0.3.0

CHANGELOG.md

@@ -5,14 +5,21 @@
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [0.3.0] 2026-03-13
+
+### Added
+
+- `GapSize` parameter on `Show-AwtrixScreen` — Control black pixel spacing
+  between LEDs to simulate the dark borders on a real matrix display
+
 ## [0.2.0] 2026-03-13
 
 ### Added
 
 - `Show-AwtrixScreen` — Render the current AWTRIX screen as colored pixels in the terminal using PwshSpectreConsole Canvas
 - `AwtrixColor` enum — Named colors (Red, Green, Blue, Yellow, Cyan, Magenta, White, Black, Orange, Purple, Pink) for intuitive color selection
 - `AwtrixIndicatorPosition` enum — Descriptive indicator positions (Top, Middle, Bottom) instead of numeric IDs
 - `AwtrixColorTransformAttribute` — Custom transform attribute for automatic color conversion across all color parameters
 - Type accelerators for `AwtrixColor`, `AwtrixIndicatorPosition`, and `AwtrixColorTransformAttribute`
 
 ### Changed
@@ -38,7 +45,7 @@
 ### Added
 
 - **Connection Management**
   - `Connect-Awtrix` — Establish a session to an AWTRIX 3 device (validates via `/api/stats`)
   - `Disconnect-Awtrix` — Clear the stored session
 
 - **Status & Retrieval**
@@ -54,8 +61,8 @@
   - `Start-AwtrixSleep` — Send the device into timed deep sleep
 
 - **Sound**
   - `Send-AwtrixSound` — Play a named sound from the MELODIES folder or DFplayer MP3
   - `Send-AwtrixRtttl` — Play an RTTTL melody string directly
 
 - **Mood Lighting**
   - `Set-AwtrixMoodlight` — Set the matrix to a color, Kelvin temperature, or disable

awtrix/Public/Show-AwtrixScreen.ps1

@@ -15,8 +15,11 @@ function Show-AwtrixScreen {
     .PARAMETER BaseUri
         The base URI of the AWTRIX device. If not specified, uses the connection from Connect-Awtrix.
     .PARAMETER PixelSize
-        Scale factor for each pixel. Default is 2, meaning each LED pixel maps to
-        a 2x2 block on the canvas for better visibility.
+        Scale factor for each pixel. Default is 1, meaning each LED pixel maps to
+        a 1x1 block on the canvas for better visibility.
+    .PARAMETER GapSize
+        Number of black pixels to insert between each LED pixel, simulating the
+        dark border between LEDs on a real matrix display. Default is 0.
     .EXAMPLE
         PS> Show-AwtrixScreen
 
@@ -40,15 +43,19 @@ function Show-AwtrixScreen {
 
         [Parameter()]
         [ValidateRange(1, 5)]
-        [int]$PixelSize = 2
+        [int]$PixelSize = 1,
+
+        [Parameter()]
+        [ValidateRange(0, 3)]
+        [int]$GapSize = 0
     )
 
     begin {
-        if (-not (Get-Module -Name PwshSpectreConsole -ListAvailable)) {
+        if (-not (Get-Module -Name PwshSpectreConsole)) {
             throw 'PwshSpectreConsole module is required. Install it with: Install-Module PwshSpectreConsole'
         }
 
-        Import-Module PwshSpectreConsole -ErrorAction Stop
+        # Import-Module PwshSpectreConsole -ErrorAction Stop
 
         $collectedData = [System.Collections.Generic.List[int]]::new()
     }
@@ -65,9 +72,14 @@ function Show-AwtrixScreen {
         if ($collectedData.Count -eq 0) {
             $fetchParams = @{}
             if ($BaseUri) { $fetchParams['BaseUri'] = $BaseUri }
-            $collectedData = [System.Collections.Generic.List[int]]::new(
-                [int[]](Get-AwtrixScreen @fetchParams)
-            )
+            try {
+                $collectedData = [System.Collections.Generic.List[int]]::new(
+                    [int[]](Get-AwtrixScreen @fetchParams -ErrorAction Stop)
+                )
+            }
+            catch {
+                $PSCmdlet.ThrowTerminatingError($_)
+            }
         }
 
         $matrixWidth = 32
@@ -78,8 +90,9 @@ function Show-AwtrixScreen {
             throw "Expected $expectedPixels pixel values (32x8) but received $($collectedData.Count)."
         }
 
-        $canvasWidth = $matrixWidth * $PixelSize
-        $canvasHeight = $matrixHeight * $PixelSize
+        $stride = $PixelSize + $GapSize
+        $canvasWidth = $matrixWidth * $stride - $GapSize
+        $canvasHeight = $matrixHeight * $stride - $GapSize
         $canvas = [Spectre.Console.Canvas]::new($canvasWidth, $canvasHeight)
 
         for ($y = 0; $y -lt $matrixHeight; $y++) {
@@ -91,19 +104,19 @@ function Show-AwtrixScreen {
                 $b = [byte]($colorInt -band 0xFF)
                 $color = [Spectre.Console.Color]::new($r, $g, $b)
 
-                # Fill the scaled pixel block
+                # Fill the scaled pixel block, leaving gap rows/columns black
                 for ($py = 0; $py -lt $PixelSize; $py++) {
                     for ($px = 0; $px -lt $PixelSize; $px++) {
-                        $canvas.SetPixel(
-                            ($x * $PixelSize) + $px,
-                            ($y * $PixelSize) + $py,
+                        $canvas = $canvas.SetPixel(
+                            ($x * $stride) + $px,
+                            ($y * $stride) + $py,
                             $color
                         )
                     }
                 }
             }
         }
 
-        [Spectre.Console.AnsiConsole]::Write($canvas)
+        $canvas | Out-SpectreHost
     }
 }

awtrix/awtrix.psd1

@@ -12,7 +12,7 @@
     RootModule = 'awtrix.psm1'
 
     # Version number of this module.
-    ModuleVersion = '0.2.0'
+    ModuleVersion = '0.3.0'
 
     # Supported PSEditions
     # CompatiblePSEditions = @()

awtrix/awtrix.psm1

@@ -13,6 +13,10 @@ foreach ($import in @($classes + $public + $private)) {
     }
 }
 
+if ( Get-Module -Name PwshSpectreConsole -ListAvailable) {
+    Import-Module PwshSpectreConsole -ErrorAction Stop
+}
+
 Export-ModuleMember -Function $public.Basename
 
 # Define the types to export with type accelerators.
@@ -29,10 +33,12 @@ $TypeAcceleratorsClass = [psobject].Assembly.GetType(
 # If a type accelerator with the same name exists, throw an exception.
 $ExistingTypeAccelerators = $TypeAcceleratorsClass::Get
 foreach ($Type in $ExportableTypes) {
-    if ($Type.FullName -in $ExistingTypeAccelerators.Keys) {
+    if ($Type.FullName -in $ExistingTypeAccelerators.Keys -and
+        # Check if it's from our assembly, if it exists. This allows re-importing the module without error.
+        $ExistingTypeAccelerators[$Type.FullName].Assembly.GetName().Name -ne 'awtrix') {
         $Message = @(
             "Unable to register type accelerator '$($Type.FullName)'"
-            'Accelerator already exists.'
+            "Accelerator already exists from assembly '$($ExistingTypeAccelerators[$Type.FullName].Assembly.GetName().Name)'."
         ) -join ' - '
 
         throw [System.Management.Automation.ErrorRecord]::new(

docs/en-US/Show-AwtrixScreen.md

@@ -13,7 +13,7 @@ Renders the current AWTRIX screen as colored pixels in the terminal.
 ## SYNTAX
 
 ```
-Show-AwtrixScreen [[-ScreenData] <Int32[]>] [[-BaseUri] <String>] [[-PixelSize] <Int32>]
+Show-AwtrixScreen [[-ScreenData] <Int32[]>] [[-BaseUri] <String>] [[-PixelSize] <Int32>] [[-GapSize] <Int32>]
  [-ProgressAction <ActionPreference>] [<CommonParameters>]
 ```
 
@@ -99,6 +99,22 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -GapSize
+Number of black pixels to insert between each LED pixel, simulating the
+dark border between LEDs on a real matrix display. Default is 1.
+
+```yaml
+Type: Int32
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: 4
+Default value: 1
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -ProgressAction
 {{ Fill ProgressAction Description }}