{"id":21893701,"url":"https://github.com/asterics/cmd-protocol-v3","last_synced_at":"2025-03-22T03:45:01.663Z","repository":{"id":201081077,"uuid":"706920589","full_name":"asterics/cmd-protocol-v3","owner":"asterics","description":"Documentation and implementation of command protocol v3, which adds mapping between trigger events and actions","archived":false,"fork":false,"pushed_at":"2024-02-17T18:57:03.000Z","size":69,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-02-03T02:52:50.078Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/asterics.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-10-18T21:35:50.000Z","updated_at":"2024-02-17T18:43:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"c340f4f6-8e8b-4361-b44b-2bc6449e502c","html_url":"https://github.com/asterics/cmd-protocol-v3","commit_stats":null,"previous_names":["asterics/cmd-protocol-v3"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asterics%2Fcmd-protocol-v3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asterics%2Fcmd-protocol-v3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asterics%2Fcmd-protocol-v3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asterics%2Fcmd-protocol-v3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/asterics","download_url":"https://codeload.github.com/asterics/cmd-protocol-v3/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244902918,"owners_count":20529114,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-28T13:16:13.158Z","updated_at":"2025-03-22T03:45:01.634Z","avatar_url":"https://github.com/asterics.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cmd-protocol-v3\n\nDocumentation and reference implementation of command protocol v3, which adds mapping between trigger events and actions.\n\n## Installation\n\n```bash\npip install -r requirements.txt\n```\n\n## Run Program\n\n```bash\npython main.py\n```\nUse the keys \u003ckbd\u003e1\u003c/kbd\u003e and \u003ckbd\u003e2\u003c/kbd\u003e to simulate button presses.\n\n## Documentation\n\n### Class diagram\n\n```mermaid\n---\ntitle: cmd protocol class diagram\n---\nclassDiagram\n    TriggerType \u003c|-- Button\n    TriggerType \u003c|-- Pressure\n    TriggerType : +TriggerState state\n    TriggerType : +Action action\n    TriggerType : +TriggerType next\n    TriggerType: +process()\n\n    TriggerType \"1\" --\u003e \"0..1\" TriggerType\n\n    class Button{\n    }\n    class Pressure{\n    }\n\n    Action \u003c|-- MouseAction\n    Action \u003c|-- IRAction\n    Action \"1\" --\u003e \"0..1\" Action\n\n    class Action{\n        +execute()\n    }\n    class MouseAction{\n    }\n    class IRAction{\n    }\n```\n\n### TriggerType Button\n\nA button trigger type can be triggered by several modalities:\n\n1. single-click\n2. double-click\n3. triple-click\n4. long-press\n5. (combination of triggers 1-4 of the same button or another one.)\n\nAll triggers can have a timeout value, which resets the current state and starts evaluating a trigger type from the beginning.\n\n### Trigger States\n\nA Trigger type is implemented as a class and maintains it's own state. \nThe states can be one of the following:\n\n* STARTED: Trigger object waits for key input to be evaluated\n* CANCELLED: Input evaluation went into timeout\n* FIRED: The Trigger object has had a valid combination of the required key inputs within the defined timeout time span.\n* NEXT: The Trigger object has had a valid combination of the required key inputs and is cascaded with a subsequent Trigger object which does further processing of key inputs now.\n\n### Example Configuration\n\n```python\n    a1 = Action(name=\"single-click action\")\n    a2 = Action(name=\"double-click action\")\n    a3 = Action(name=\"triple-click action\")\n    a4 = Action(name=\"long press action\")\n    a5 = Action(name=\"combined action\")\n\n    # Button 1, single-click\n    b1=Button(name=\"b1\",source=1,mode=\"pressed\",count=1, timeout=400,action=a1)\n    # Button 1, double-click\n    b2 = Button(name=\"b2\",source=1, mode=\"pressed\", count=2, timeout=400, action=a2)\n    # Button 1, triple-click\n    b3 = Button(name=\"b3\",source=1, mode=\"pressed\", count=3, timeout=400, action=a3)\n    # Button 1, long press\n    b4 = Button(name=\"b4\", source=1, mode=\"long_pressed\", count=1, timeout=600, duration=100, action=a4)\n    # Button 1 single-click + Button 2 single-click\n    b5 = Button(name=\"b5\", source=1, mode=\"pressed\", count=1, timeout=200,\n                next_trigger=Button(name=\"b5a\", source=2, mode=\"pressed\", count=1, timeout=200, action=a5)\n```\n### Algorithm\n\nThe trigger mappings must be grouped by trigger_type (e.g. button and source number) and then sorted by priority within that group.\n\n#### Example\n\n1. Button 1, long press\n2. Button 1, triple-click\n3. Button 1, single-click + Button 2, single-click\n4. Button 1, double-click\n5. Button 1, single-click\n\n```python\n   trigger_defs=[b4,b3,b5,b2,b1]\n```\n\n#### Evaluation\n\nA button press is then propagated to all trigger mappings and the action is executed according to the following flowchart:\n\n```mermaid\n  graph TD;\n      A[Start] --\u003eB4{B4 Fired?};\n      B4 -- Yes --\u003e A4[Execute Action A4]\n      B4 -- No --\u003e B3{B3 Fired?};\n      B3 -- Yes --\u003e A3{Execute Action A3}\n      B3 -- No --\u003e B5{B5 Fired?}\n      B5 -- Yes --\u003e A5{Execute Action A5}\n      B5 --\u003e No --\u003e B2{B2 Fired?}\n      B2 -- Yes --\u003e A2[Execute Action A2]\n      B2 -- No --\u003e A1[Execute Action A1]\n```\n\n### Cases to be supported\n\n* Button 1 Press --\u003e Immediate action\n* Button 1 Release --\u003e Immediate action\n* Combined execute either A or B (internally pause normal mouse action):\n  * A: Strong Sip + Button 1 Press\n  * B: Button Press 1\n* Button 1 Long Press (after duration) --\u003e action\n* Button 2 Press --\u003e Immediate action\n\n* Detection with debouncing and tremor filters\n* Test cases with morse code logic\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasterics%2Fcmd-protocol-v3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasterics%2Fcmd-protocol-v3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasterics%2Fcmd-protocol-v3/lists"}