Large update/upgrade

.gitignore

@@ -1,9 +1,13 @@
+# If you prefer the allow list template instead of the deny list, see community template:
+# https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore
+#
 # Binaries for programs and plugins
 *.exe
 *.exe~
 *.dll
 *.so
 *.dylib
+__debug_bin
 
 # Test binary, built with `go test -c`
 *.test
@@ -14,6 +18,9 @@
 # Dependency directories (remove the comment below to include it)
 # vendor/
 
+# Go workspace file
+go.work
+
 # TinyGo
 *.elf
 *.uf2

README.md

@@ -83,6 +83,37 @@ Ctrl + Shift + P > Tasks: Run Build Task
 
 TODO
 
-## Why should I use this?
+## Debugging using a browser
+
+**NOTE**: This is a beta feature! Please do not expect it to function properly, if at all.
+
+If your EuroPi project is set up via the `europi.Bootstrap()` execution paradigm, you may operate and visualize it via a browser instead of having to flash it to a EuroPi hardware module or build it via TinyGo.
+
+There are some caveats that must be understood before using this functionality:
+1. This builds via Pure Go and only simulates (to the best of ability) a RP2040 / Pico running the software.
+1. The visualization web page is terrible. While some care was taken to make it minimally usable, it's not pretty and is rife with bugs.
+1. The websocket interface presented can currently only bind to port 8080 on "all" network interfaces.
+1. Projects which do not utilize the `europi.Bootstrap()` execution paradigm will not be able to partake in this functionality.
+1. [pprof](https://github.com/google/pprof/blob/main/README.md) support is enabled while the websocket interface is available, but it does not represent how the code will run on a RP2040 / Pico or within a EuroPi module. It is specifically provided here for debugging multiprocessing functionality and gross abuses of memory and CPU. 
+
+### How to get the browser support to work
+
+First, you need [Go installed](https://go.dev/doc/install). Preferably 1.18 or newer.
+
+Second, set up your module project to build with the `europi.Bootstrap()` execution paradigm and add the following line to the `europi.Bootstrap()` parameter list:
+
+```go
+europi.AttachNonPicoWS(true),
+```
+
+Then, execute your module using Go (not TinyGo) and pass a buildflag tag parameter matching [which revision of hardware](hardware/README.md#revision-list) you want to run, like so:
+
+```bash
+go run -tags=revision1 internal/projects/randomskips/randomskips.go
+```
+
+Finally, open up a browser to [localhost:8080](http://localhost:8080/) to see your module in action!
+
+## Why should I use the TinyGo version of the EuroPi firmware?
 
 You probably shouldn't. This is my passion project because I love Go. You should probably be using the official [EuroPi firmware](https://github.com/Allen-Synthesis/EuroPi). But if you are interested in writing a dedicated script for the EuroPi that requires concurrency and faster performance than MicroPython can offer, then maybe this is the right firmware for you!

clamp/clamp.go

@@ -0,0 +1,15 @@
+package clamp
+
+type Clampable interface {
+	~int8 | ~int16 | ~int32 | ~int64 | ~int | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~float32 | ~float64
+}
+
+func Clamp[T Clampable](v, min, max T) T {
+	if v > max {
+		v = max
+	}
+	if v < min {
+		v = min
+	}
+	return v
+}

clamp/clamp_test.go

@@ -0,0 +1,41 @@
+package clamp_test
+
+import (
+	"testing"
+
+	"github.com/awonak/EuroPiGo/clamp"
+)
+
+func TestClamp(t *testing.T) {
+	t.Run("InRange", func(t *testing.T) {
+		t.Run("Min", func(t *testing.T) {
+			min, max := 0, 10
+			if expected, actual := min, clamp.Clamp(min, min, max); actual != expected {
+				t.Fatalf("Clamp[%v, %v] Clamp: expected[%v] actual[%v]", min, max, expected, actual)
+			}
+		})
+
+		t.Run("Max", func(t *testing.T) {
+			min, max := 0, 10
+			if expected, actual := max, clamp.Clamp(max, min, max); actual != expected {
+				t.Fatalf("Clamp[%v, %v] Clamp: expected[%v] actual[%v]", min, max, expected, actual)
+			}
+		})
+	})
+
+	t.Run("OutOfRange", func(t *testing.T) {
+		t.Run("BelowMin", func(t *testing.T) {
+			min, max := 0, 10
+			if expected, actual := min, clamp.Clamp(min-2, min, max); actual != expected {
+				t.Fatalf("Clamp[%v, %v] Clamp: expected[%v] actual[%v]", min, max, expected, actual)
+			}
+		})
+
+		t.Run("AboveMax", func(t *testing.T) {
+			min, max := 0, 10
+			if expected, actual := max, clamp.Clamp(max+2, min, max); actual != expected {
+				t.Fatalf("Clamp[%v, %v] Clamp: expected[%v] actual[%v]", min, max, expected, actual)
+			}
+		})
+	})
+}

debounce/debounce.go

@@ -0,0 +1,34 @@
+package debounce
+
+import "time"
+
+type Debouncer[T func(U, time.Duration), U any] interface {
+	Debounce(delay time.Duration) func(U)
+	LastChange() time.Time
+}
+
+type debouncer[T func(U, time.Duration), U any] struct {
+	last time.Time
+	fn   T
+}
+
+func NewDebouncer[T func(U, time.Duration), U any](fn T) Debouncer[T, U] {
+	return &debouncer[T, U]{
+		last: time.Now(),
+		fn:   fn,
+	}
+}
+
+func (d *debouncer[T, U]) Debounce(delay time.Duration) func(U) {
+	return func(u U) {
+		now := time.Now()
+		if deltaTime := now.Sub(d.last); deltaTime >= delay {
+			d.last = now
+			d.fn(u, deltaTime)
+		}
+	}
+}
+
+func (d debouncer[T, U]) LastChange() time.Time {
+	return d.last
+}

debounce/debounce_test.go

@@ -0,0 +1,89 @@
+package debounce_test
+
+import (
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/awonak/EuroPiGo/debounce"
+)
+
+func TestDebouncer(t *testing.T) {
+	t.Run("New", func(t *testing.T) {
+		fn := func(any, time.Duration) {}
+		if actual := debounce.NewDebouncer(fn); actual == nil {
+			t.Fatalf("Debouncer[%p] NewDebouncer: expected[non-nil] actual[nil]", fn)
+		}
+	})
+
+	t.Run("Debounce", func(t *testing.T) {
+		t.Run("Delay0", func(t *testing.T) {
+			t.Parallel()
+			delay := time.Duration(0)
+			runs := 4
+			runDebouncerTest(t, runs, delay, time.Duration(0), 4)
+			runDebouncerTest(t, runs, delay, time.Millisecond*1, 4)
+			runDebouncerTest(t, runs, delay, time.Second*1, 4)
+		})
+
+		t.Run("Delay100ms", func(t *testing.T) {
+			t.Parallel()
+			delay := time.Millisecond * 100
+			runs := 4
+			runDebouncerTest(t, runs, delay, time.Duration(0), 0)
+			runDebouncerTest(t, runs, delay, time.Millisecond*1, 0)
+			runDebouncerTest(t, runs, delay, time.Second*1, 2)
+		})
+
+		t.Run("Delay10s", func(t *testing.T) {
+			t.Parallel()
+			delay := time.Millisecond * 100
+			runs := 4
+			runDebouncerTest(t, runs, delay, time.Duration(0), 0)
+			runDebouncerTest(t, runs, delay, time.Millisecond*1, 0)
+			runDebouncerTest(t, runs, delay, time.Second*1, 0)
+		})
+	})
+
+	t.Run("LastChange", func(t *testing.T) {
+		fn := func(any, time.Duration) {}
+		db := debounce.NewDebouncer(fn)
+		dbFunc := db.Debounce(0)
+
+		beforeExpected := time.Now()
+		dbFunc(nil)
+		if actual := db.LastChange(); !actual.After(beforeExpected) {
+			t.Fatalf("Debouncer[%p] LastChange: expected(after)[%v] actual[%v]", fn, beforeExpected, actual)
+		}
+	})
+}
+
+func runDebouncerTest(t *testing.T, runs int, delay, interval time.Duration, minimumExpected int) {
+	t.Helper()
+
+	var testName string
+	if interval == 0 {
+		testName = "Immediate"
+	} else {
+		testName = fmt.Sprintf("Interval%v", interval)
+	}
+
+	var actual int
+	fn := func(any, time.Duration) {
+		actual++
+
+	}
+
+	db := debounce.NewDebouncer(fn).Debounce(delay)
+
+	t.Run(testName, func(t *testing.T) {
+		for i := 0; i < runs; i++ {
+			db(nil)
+			time.Sleep(interval)
+		}
+		// since these are timing-based, we have to be lenient
+		if actual < minimumExpected {
+			t.Fatalf("Debouncer[%p] Debounce(%v): expected[%v] actual[%v]", fn, delay, minimumExpected, actual)
+		}
+	})
+}