Open Macro Keyboard

[spook]

Jestem sporym maniakiem klawiatur makro - mam Stream Decka, Loupe Decka i sam zbudowałem kilka własnych klawiatur makro. Przy okazji projektowania i składania ostatniej wpadłem jednak na pomysł, by z efektów mojej pracy mogli skorzystać również inni maniacy DIY i zaprojektowałem otwartą software'ową platformę, która ułatwia zbudowanie funkcjonalnej klawiatury makro (potencjalnie o możliwościach Stream Decka).

Skąd pomysł?

Klawiatury makro działają na jeden z dwóch sposobów. Pierwszy z nich to udawanie urządzeń HID. Implementacja na większości mikrokontrolerów zgodnych z Arduino jest banalna, bo przeważająca ich większość potrafi udawać dowolne urządzenie HID (klawiatura, mysz, joystick, urządzenie MIDI). Z drugiej jednak strony tak zaimplementowana klawiatura makro ma bardzo ograniczone możliwości - zazwyczaj tylko w postaci symulowania wciśnięć kombinacji klawiszy lub ich sekwencji. Pozwala to na zautomatyzowanie skrótów klawiaturowych i jakichś bardzo prostych zadań, ale te bardziej skomplikowane albo wymagają zastosowania sztuczek (na przykład zasymulowanie wciśnięcia skrótu Win+R w celu uruchomienia programu), albo ich realizacja jest wręcz całkowicie niemożliwa.

Tego typu klawiatura makro ma też tę wadę, że zazwyczaj pozwala na zautomatyzowanie tylko tylu operacji, ile ma klawiszy. Bardziej ambitne pozwalają na przełączanie trybów pracy, ale i tych jest często ograniczona liczba.

Drugim podejściem do budowania klawiatury makro jest zaprojektowanie jej w postaci terminala. Firmware wykrywa wciśnięcia klawiszy i bezmyślnie przesyła je do komputera. Tam z kolei informacje te odbiera specjalny program, a następnie realizuje zadania, które są do poszczególnych klawiszy przypisane. Rozwiązanie to ma szereg zalet:

• Możliwości automatyzacji są prawie nieograniczone
• Istnieje możliwość zdefiniowania różnych "ekranów" klawiatury (podobnie, jak ma to miejsce w Stream Decku), dzięki czemu możemy zdefiniować praktycznie dowolną liczbę makr dla klawiszy
• Implementacja oprogramowania dla klawiatury jest banalna i często wręcz nie wymaga zastosowania żadnych bibliotek.

Wadą tego rozwiązania jest z kolei konieczność napisania programu na komputer, który będzie wykrywał wciśnięcia klawiszy i realizował zlecane klawiaturze zadania.

No i właśnie ten problem rozwiązuje mój framework o nazwie Open Macro Keyboard (FOSS na solidnej licencji MIT, a nie jakiejś tam wirusowej GNU GPL)

W skrócie, mamy do dyspozycji program, który:

• Pozwala na dodanie i obsługę jednej lub większej liczby klawiatur makro;
• Domyślnie odbiera informacje o wciśnięciach klawiszy przez port szeregowy, ale można go dosyć łatwo rozszerzyć o odbieranie takich informacji w zupełnie dowolny sposób (po sieci, przez Bluetooth etc.);
• Zawiera wygodny edytor w stylu drag&drop (podobny do tego ze Stream Decka), który pozwala na łatwe definiowanie ekranów z makrami;
• Pozwala na implementowanie własnych akcji (poza tymi domyślnie dostępnymi), a następnie łatwe dołączanie ich do programu w postaci małych wtyczek;
• Jest napisany w C# (z niewielką częścią w C++), wraz z zestawem dodatkowych klas, za pomocą których można w banalny sposób dodawać klawiatury o (prawie) dowolnych rozmiarach oraz zawierających enkodery;
• Zawiera gotowe implementacje sterowników dla standardowych układów klawiatur (3x3, 4x3, 4x4, 5x4 i 5x5), a niedługo pojawią się również podobne definicje z enkoderami (jeżeli zaprojektowana przez kogoś klawiatura pasuje do takiego generycznego układu, to nie musi on robić nic, tylko odpalić aplikację, dodać odpowiednią klawiaturę i już)
• Gotowe klasy, które ułatwiają implementowanie własnych sterowników domyślnie obsługują również klawiatury podświetlane LEDami RGB:

Aplikacja startuje i pracuje w systemowym tray'u, a po kliknięciu w jej ikonkę pokazuje się główne okno (na powyższym screenie). Tam możemy dodawać i zarządzać klawiaturami. Możliwe jest też edytowanie układów ekranów wraz z poszczególnymi makrami przypisanymi do klawiszy. Wystarczy tylko przeciągnąć jedno z makr z biblioteki po prawej stronie nad klawisz lub nad specjalne pole w konfiguracji klawisza, a potem odpowiednio je skonfigurować - ot i cała filozofia. Dostępne są też katalogi, więc hierarchię ekranów można rozszerzać praktycznie w nieskończoność.

Możliwe jest również eksportowanie i importowanie profili - podobnie, jak w Stream Decku.

Co jeszcze wyróżnia Open Macro Keyboard? Ano to, że jeśli nie macie fancy klawiatury z diodami RGB (ta na zdjęciu to chyba 3. sztuka, którą zmontowałem i działa, ale wymaga podłączenia do portu USB 3), to mimo wszystko możecie wygodnie korzystać z katalogów i rozszerzać możliwości swoich klawiatur. Po wciśnięciu dowolnego klawisza na dłużej niż 300ms, Open Macro Keyboard pokazuje nad systemowym trayem podpowiedź dotyczącą bieżącego ekranu:

Podpowiedź pozostaje widoczna podczas nawigacji pomiędzy katalogami, a potem po 5 sekundach znika. Dzięki temu nawet najprostsze klawiatury makro mają szansę stać się równie funkcjonalne jak Stream Deck.

W jaki sposób oprogramować klawiaturę, aby była zgodna z Open Macro Keyboard?

1. Jeżeli klawiatura ma generyczny układ i implementuje protokół Open Macro Keyboard (o nim zaraz), to wystarczy użyć istniejących, generycznych sterowników:

2. Jeżeli klawiatura nie ma generycznego układu (na przykład ma enkoder), ale implementuje protokół Open Macro Keyboard, to trzeba napisać własny sterownik, ale można oprzeć się o gotowe klasy, co zamyka cały kod sterownika takiej klawiatury w ok. 50 linijkach kodu C#.

3. Jeżeli klawiatura nie implementuje protokołu Open Macro Keyboard, to trzeba napisać własny sterownik, czyli klasę, która będzie stanowiła mostek pomiędzy klawiaturą a Open Macro Keyboard.

Protokół Open Macro Keyboard jest banalny i opiera się na przesyłaniu przez klawiaturę krótkich, tekstowych komunikatów poprzez wirtualny port szeregowy (COM przez USB):

• Po naciśnięciu przez użytkownika klawisza, klawiatura powinna przesłać bxxd; , gdzie xx to dwucyfrowy numer klawisza, np. b01d; (wciśnięty drugi klawisz)
• Po puszczeniu przez użytkownika klawisza, klawiatura powinna przesłać bxxu; , gdzie xx to dwucyfrowy numer klawisza, np. b01u; (puszczony drugi klawisz)
• Po obróceniu enkodera zgodnie z ruchem wskazówek zegara, klawiatura powinna przesłać exx+; , gdzie xx to numer enkodera, np. e01+;
• Po obróceniu enkodera przeciwnie do ruchu wskazówek zegara, komunikat powinien brzmieć exx-; , gdzie xx to numer enkodera, np. e01-;
• Po wciśnięciu enkodera (jeśli to obsługuje), komunikat powinien brzmieć exxd; , gdzie xx to numer enkodera, np. e01d;
• Po puszczeniu enkodera (jeśli to obsługuje), komunikat powinien brzmieć exxu; , gdzie xx to numer enkodera, np. e01u;

I tyle! To wystarczy, by klawiaturę można było łatwo zintegrować z moim frameworkiem.

Kompletne źródła Open Macro Keyboard, w skład których wchodzi cała aplikacja desktopowa, schematy dwóch klawiatur (w tym tej ze zdjęcia) zaprojektowane w KiCad, projekty obudowy (jako archiwum Fusion 360) oraz program dla Raspberry Pi Pico dla tychże klawiatur znajdziecie na stronie: https://gitlab.com/spook/OpenMacroKeyboard . Znajduje się tam też obszerny opis frameworka (po angielsku). I teraz:

• Do zbudowania aplikacji desktopowej aplikacji potrzebne jest Visual Studio 2022 (może być darmowa wersja Community)
• Do zbudowania firmware'u dla klawiatur potrzebne jest pełne SDK Raspberry Pi Pico.

Możecie również obejrzeć moje wprowadzenie do Open Macro Keyboard (po angielsku):

A także, co chyba bardziej ciekawe, przykładową integrację (na jej potrzeby użyłem jednej z moich starych klawiatur makro, które działały jeszcze w pierwszym opisanym przeze mnie wcześniej modelu):

Jeżeli ktoś zdecyduje się zaprojektować własną klawiaturę makro zgodną z Open Macro Keyboard, dawajcie znać w tym wątku. Warto wspomnieć, że jeżeli macie już własne klawiatury makro, to wystarczy tylko przeprogramować je, aby były zgodne z protokołem (jak na drugim filmiku). Mam nadzieję, że moje długie godziny pracy komuś jeszcze się przydadzą  

[matsobdev]

Ja nic nie mówię, ale są małe wyświetlacze (choć pewnie luzem łatwiej kupić i z taśmą do lutowania niż FPC). Kurcze, gdzieś w ciekawych filmach jest odlewanie własnego przycisku z wyświetlaczem. Nic odkrywczego nie wymyślam oczywiście, ale wynik może być ciekawy.

Co do HID i skrótów klawiszowych, to Windowsowe skróty (*.lnk) umożliwiają przypisanie skrótów klawiszowych, a tutaj to już wszystko można odpalić skryptem (przynajmniej PowerShell zrobi wszystko co da się w systemie zrobić), którego wykonanie nie będzie widoczne: skrypt *.vbs plus ewentualnie *.bat, czy *.ps1. Ja tam nie jestem wielkim programistą, ale podglądam i np. tą "sztuczkę" podejrzałem w Scrcpy.

Edytowano Maj 10, 2024 przez matsobdev

[spook]

Małe wyświetlacze pod przyciskami to jest katorga - masa roboty, żeby wszystkie podłączyć, zamocować i jeszcze przygotować przycisk, który będzie nad nimi działał (możemy zapomnieć o standardowych Cherry MXach lub im podobnych). Stream Deck rozwiązuje ten problem znacznie sprytniej: stosuje tylko jeden duży wyświetlacz, nad którym umieszczona jest płytka z otworami i krawędziami dookoła otworów wrażliwymi na dotyk (zgaduję, że działa to podobnie do pojemnościowego ekranu dotykowego). Nad nią z kolei znajdują się przyciski, które po wciśnięciu dotykają tych wrażliwych obszarów (wszystko widać dosyć dobrze na przykład tu).

Jeżeli chodzi o Windowsowe skróty, to wydaje mi się, że ten pomysł kwalifikuje się idealnie do tego, o czym wspominałem wcześniej, czyli do obchodzenia ograniczeń. Takie rozwiązanie ma bowiem cały szereg wad:

• Pliki skrótów muszą być umieszczone w odpowiednich katalogach
• Różne wersje Windows w różny sposób podchodza do skrótów klawiaturowych - zmienia się to z wersji na wersję, co potencjalnie wymaga ciągłego dostosowywania skrótów. Na przykład w Windows 7 można było rejestrować globalne skróty z użyciem klawisza Windows. W Windows 10 (chyba nawet 8 ) jest to już niemożliwe.
• Skrótów jest ograniczona liczba - mogą one również kolidować ze skrótami używanych aplikacji
• PowerShell teoretycznie daje możliwość "pisania" w .NET, ale implementowanie jakichkolwiek bardziej złożonych rozwiąząń to droga przez mękę. Dla przykładu, jeden z domyślnie dostępnych pluginów w Open Macro Keyboard pozwala na szybkie przełączenie się do głównego okna procesu o zadanej nazwie pliku wykonywalnego (np. devenv.exe dla Visual Studio, spotify.exe dla Spotify i tak dalej). Zaimplementowałem to w C++ (bo korzystam z WinAPI oraz z COM w celu aktywowania okna - inaczej praktycznie się nie da). Powodzenia z pisaniem tego w PowerShellu.
• PowerShell jest wolny, bo jest językiem interpretowanym. Możemy więc zapomnieć np. o szybkim wykonaniu kilku operacji jedna po drugiej.
• Aby móc uruchamiać pliki ze skryptami, trzeba albo je cyfrowo podpisać albo wymusić na systemie operacyjnym możliwość uruchamiania potencjalnie niebezpiecznych skryptów. To samo jest z .vbs - szczególnie w tym przypadku wyłączanie zabezpieczeń systemowych jest ryzykowne, bo masa złośliwego oprogramowania jest zaimplementowana właśnie jako skrypty .vbs
• Pliki PowerShell + LNK stanowią efektywny "profil". Można się nim dzielić z innymi, ale jest to dosyć niebezpieczne, bo w takich skryptach można zawrzeć zupełnie dowolny kod - w tym złośliwy. OpenMacroKeyboard eksportuje profile do pliku .xml niezawierającego niczego, co dałoby się bezpośrednio uruchomić (choć oczywiście można np. przybindować do przycisku link do złośliwej strony, tego nie da się uniknąć).
• Bez dodatkowego oprogramowania niemożliwe jest przygotowanie profili pod uruchomioną aplikację (w sensie, klawiatura makro przełącza się na określony ekran w zależności od tego, która aplikacja w danym momencie jest aktywna). OpenMacroKeyboard w tej chwili nie ma jeszcze takiej funkcjonalności, ale jeśli projektem zainteresuje się więcej osób, to planuję coś takiego dopisać.
• Bez dodatkowego oprogramowania niemożliwe jest zastosowanie odrębnych "ekranów", czyli przyporządkowań akcji do klawiszy. Jedną z największych zalet Open Macro Keyboard jest to, że umożliwia podgląd bieżącego "ekranu" na wyświetlaczu komputera nawet w przypadku klawiatur, które nie mają żadnej metody przekazania feedbacku dla użytkownika (np. diody czy wyświetlacz).
• Bez dedykowanej aplikacji na PC, skróty klawiaturowe muszą być zaszyte w firmware klawiatury - ich modyfikacja wymaga przeprogramowania mikrokontrolera

Ogólnie wszystko zależy od potrzeb. Jeżeli ktoś potrzebuje tylko uruchomić kilka aplikacji i ewentualnie zautomatyzować kilka skrótów klawiaturowych, to rozwiązanie z plikami .ps1 może się sprawdzić. Chociaż gdyby się nad tym chwilę zastanowić, to to wszystko jest już dostępne za darmo w Open Macro Keyboard, zadziała szybciej, implementacja firmware dla klawiatury jest łatwiejsza (przesłanie kilku komunikatów tekstowych za pomocą klasy Serial) i jednorazowa, no i wreszcie Open Macro Keyboard pozwala potem rozbudowywać możliwości klawiatury bez konieczności przeprogramowywania jej - osobiście nawet w takim prostym przypadku chyba też skorzystałbym z zaprezentowanego frameworka 

Pozdrawiam -- Spook.

Edytowano Maj 22, 2024 przez spook

[Techkubas]

Cześć. Bardzo fajny projekt, w wolnej chwili spróbuję na nowo stworzyć swojego Stream decka z wykorzystaniem OMK. W swojej pierwszej wersji wykorzystałem właśnie Arduino Leonardo (enkoder, klawisz, klawisz, enkoder / 4x klawisz / 4x klawisz + jeszcze jeden enkoder do sterowania głośnościa i jeden klawisz powrotu). Chciałem móc korzystać z folderów w moim stream decku, jednak aby nie pogubić się w skrótach dodałem ekran LCD 128x64 który został mi z drukarki 3D. Nie podobało mi się jednak to rozwiązanie i nie było zbyt kompaktowe.
W drugiej wersji postanowiłem ponownie wykorzystać ekran z drukarki 3D, tym razem Bigtreetech TFT35 v2. Niestety procesor wbudowany w ten ekran to STM32 z którym nigdy wcześniej nie miałem styczności, dlatego nie chciałem z jednej strony pisać całego programu od nowa i programować ten układ. Zrobiłem jednak częściową inżynierie wsteczną i udało mi się rozszyfrować jak wrzucić własne obrazu, własne podpisy pod danym przyciskiem na ekranie, jak zrobić następne strony i zmieniłem ilośc ikon z 2x4 na 3x5. Komunikację z PC zrobiłem od d**y strony i naciśnięcie danego przycisku na ekranie wysyła komende strona_przycisk (np. 1_1) do Arduino Pro Micro które odczytuje po Serialu komende z STM. Następnie wywołuje dane kombinację przyciśnięć pod PC, ponieważ działa jako urządzenie HID.

Minusem tego rozwiązania była potrzeba edycji 6 plików, aby zmienić coś zmienić. Nazwy zdjęć, opisy przycisków, nazwy zmiennych, konfiguracja makr dla Arduino Leonardo, przygotowanie zdjęć w odpowiedniej rozdzielczości, zgranie to na kartę, skompilowanie programu, aktualizacja oprogramowania w ekraniku, aktualizacja programu w Arduino. W między czasie zrobiłem aplikacje webową która edytowała automatycznie te pliki (wycinała odpowiedni fragment i dodawała nowy z nowymi nazwami, zmiennymi itp), przygotowywała odpowiednio zdjęcia oraz nagrywała wciśnięte przyciski na klawiaturze i przerabiała je na kod do Arduino. Później przemyślałem to, że nie nazwy zmiennych nie muszą się zmieniać tylko wystarczy zrobić strona_przycisk.
Tak więc z tego co dobrze pamiętam (bawiłem się z tym 2 lata temu, a aktualnie ekran wrócił do drukarki), odeszła potrzeba konfigurowania, kompilowania i wgrywania firmware'u do ekranu. Trzeba jednak wyciągnać z niego kartę na której przechowywane są zdjęcia i wgrać nowe, oraz tłumaczenia zmiennych strona_przycisk na odpowiedni opis do danego przycisku. Potrzeba też zaaktualizować Arduino, aby wywoływał nową kombinację klawiszy HID.

Niestety tak jak opisałeś na samym początku HID ma swoje wady, a twoje rozwiązanie wydaje się lepszym/ bardziej kompletnym pomysłem.

Wyświetlanie na ekranie podpowiedzi dotyczących wybranego katalogu jest fajne, jednak nie przezwycięży ekranu w DIY Stream Decku na którym cały czas wyświetlają się nam aktualne skróty. Nie zagłebiłem się jeszcze w kod OMK i nie ukrywam nie pisałem nigdy aplikacji desktopowej, więc może ty masz pomysł lub zrobiłeś w między czasie wersję z dotykowym ekranem na którym wyświetlają się cały czas przyciski. Program w takim wypadku musiał by wysyłać ikony/opisy za każdym razem po przejsciu do innego folderu do Arduino/Pico, a on rysowałby je na ekranie?

Edytowano Styczeń 10, 2025 przez Techkubas

[spook]

OpenMacroKeyboard obsługuje już w tej chwili Stream Decka, więc w kodzie znajdziesz przykład obsługi obrazów i opisów.

W skrócie, musisz napisać swój "sterownik" - mały assembly w C#, który będzie dostawał informacje od OMK na temat bieżącego ekranu i którego zadaniem będzie przepchnięcie tych informacji do urządzenia. Stream Deck akceptuje po prostu pliki JPG, w Twoim przypadku prawdopodobnie trzeba będzie wysyłać dane nieskompresowane.

Zacznij od obejrzenia sterownika do Stream Decka (współpraca z aplikacją w zakresie opisów i ikon) potem obejrzyj te dla klawiatur generycznych (przesyłanie danych przez port szeregowy) i na koniec napisz swój, dla Twojego urządzenia. Informacyjnie, te "sterowniki" to nic skomplikowanego, za mojej pamięci żaden z nich nie przekracza 200 linijek kodu w C#.

Pozdrawiam -- Spook.

[Techkubas]

Cześć. Stworzyłem sobie narazie Stream Decka na podstawie Numpada z starej klawiatury, kilku dodatkowych enkoderó i Arduino Nano. Całość działa ok, zmieniłem sobie parę rzeczy, jak układ menu edycji układu ponieważ przy układzie numpada z jednym dodatkwoym wierszem, guziki Ok i anuluj chowały się pod paskiem zadań, wydłużyłem też potrzebny czas przyciśniecia, ponieważ czasami okno skrótów pojawiało się po zwykłym naciśnięciu klawisza.

Mam jednak 2 problemy.

1. Korzystam raz z laptopa, a raz z komputera. Urządzenia mam podłaczone przez KVM więc nie muszę przepinać "Stream dekca", jednak potrzeba by było eksportować i importować plik omkprofile z danym układem skrótów między urządzeniami. Czy istnieje gdzieś podobny plik z któego korzysta OMK bez potrzeby importu i eksportu, aby można było go synchronizować za pomocą Syncthing, czy po prostu synchronizować cały skompilowany folder OMK?
2. Czasami OMK nie wykrywa automatycznie klawiatury, potrzebne jest ponowne uruchomienie programu / odłaczenie Stream Decka / wybranie Połącz ponownie w programie. Czym może to być spowodowane?

[spook]

Hej,

Nie wiem, czemu nie zauważyłem Twojego postu  Ale już odpisuję.

Open Macro Keyboard przechowuje ustawienia w katalogu użytkownika, C:\Users\<użytkownik>\AppData\Roaming\Spooksoft\OpenMacroKeyboard.

Jeśli chodzi o ponowne połączenie, prawdę mówiąc nie przychodzi mi nic do głowy. Jeśli znasz C#, możesz spróbować napisać automatyczne ponawianie prób połączenia po jakimś okresie czasu, być może na przykład Windows najpierw uruchamia aplikację, a dopiero potem podłącza urządzenie przez USB i aplikacja próbuje połączyć się z klawiaturą, gdy ta nie jest jeszcze dostępna w systemie.

Pozdrawiam -- Spook.

[spook]

Dla wszystkich zainteresowanych, po kilku iteracjach zaprojektowałem wreszcie końcową wersję płytki klawiatury, która działa już bez problemów. Jeżeli ktoś ma ochotę się taką klawiaturą pobawić, wystawiłem ją na Allegro (mam obecnie dostępne 2 sztuki):

https://allegrolokalnie.pl/oferta/klawiatura-makro-z-podswietleniem-led-rgb

Załączam z tym postem również informacje na temat klawiatury i sposoby, na jakie można jej używać.

Pozdrawiam -- Spook.

Open Macro Keyboard v3 rev.pdf

Edytowano Maj 5, 2025 przez spook