{"id":13340354,"url":"https://github.com/fx-bricks/pfx-brick-vscode","last_synced_at":"2025-03-11T17:30:30.264Z","repository":{"id":108595390,"uuid":"300495281","full_name":"fx-bricks/pfx-brick-vscode","owner":"fx-bricks","description":"Language support extension to Visual Studio Code for the PFx Brick scripting language.","archived":false,"fork":false,"pushed_at":"2021-08-01T14:00:22.000Z","size":657,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-24T04:28:34.219Z","etag":null,"topics":["extension","language","pfx","pfxbrick","scripting","visual-studio-code"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fx-bricks.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,"publiccode":null,"codemeta":null}},"created_at":"2020-10-02T03:59:08.000Z","updated_at":"2021-11-07T20:39:37.000Z","dependencies_parsed_at":"2023-08-22T21:30:45.378Z","dependency_job_id":null,"html_url":"https://github.com/fx-bricks/pfx-brick-vscode","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fx-bricks%2Fpfx-brick-vscode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fx-bricks%2Fpfx-brick-vscode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fx-bricks%2Fpfx-brick-vscode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fx-bricks%2Fpfx-brick-vscode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fx-bricks","download_url":"https://codeload.github.com/fx-bricks/pfx-brick-vscode/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243079049,"owners_count":20232921,"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":["extension","language","pfx","pfxbrick","scripting","visual-studio-code"],"created_at":"2024-07-29T19:22:32.458Z","updated_at":"2025-03-11T17:30:30.258Z","avatar_url":"https://github.com/fx-bricks.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"![Logo](./images/PFxLogo128px.png)\n\n# PFx Brick scripting for Visual Studio Code \n\n![https://github.com/fxbricks/pfx-brick-vscode/blob/master/LICENSE](https://img.shields.io/badge/license-MIT-blue.svg)\n\n\nThis repository contains a language support extension to Visual Studio Code for the [PFx Brick](https://www.fxbricks.com/pfxbrick) scripting language.\n\nThe PFx Brick scripting language is based on a very simple syntax. Script files are plain text files with the `.pfx` file extension.\n\n## Syntax Highlighting\n\nThis extension provides convenient syntax highlighting for working with PFx Brick script files.\n\n![Sample](./images/sample.png)\n\n\n## Installation\n\nInstalling the language extension is easy using `vsix` package bundle included in this repository.  To install the extension:\n\n1. Select the Extensions icon in the VSCode side bar\n2. Select the (...) menu at the top of the sidebar \n3. Select `Install from VSIX...` from the menu\n4. Select the `pfxbrick-X.X.X.vsix` file\n\n## Scripting Actions\n\nAs of ICD version 3.37 (and PFx Brick firmware versions 1.40+), the ability to execute complex actions and behaviours defined in script files was added. Script files are simple, human readable text files stored in the PFx Brick file system. These files conform to a simple script language syntax described later in this document. The scripting capability can be summarized as follows:\n\n1. Scripts are ASCII text files stored in the PFx Brick file system.\n2. Scripts execute one at a time. Executing another script will terminate the current script and\nstart the new one.\n3. Scripts can be executed either by using an Event/Action (with the `COMMAND` byte) or with the\nICD message `PFX_CMD_RUN_SCRIPT`.\n4. Script execution is sequential line-by-line from the start of the file to the end. At the end, the\nscript will either stop or repeat if a repeat command is the last line.\n5. Script lines with bad syntax are ignored and script execution will continue to the next line.\n\n## Loading Scripts\n\nScript files can be loaded on to the PFx Brick using the PFx App or by using other 3rd party software to copy files from a host PC to the PFx Brick. \n\nCreating script files or making changes to a script must be made on a host PC using any standard text editor (e.g. Windows Notepad, macOS Text Editor, and of course VS Code) To modify a script file, the old one must be removed from the PFx Brick file system and then replaced with a new copy (with the same file ID).\n\nThis PFx App update makes the process of quickly testing script files easier by letting you run/stop scripts directly from the PFx App.  To run a script, simply click a recognized script file, and click the `Test/Run` button. Note that the script file must already be copied to the PFx Brick (the PFx circle indicator on the right column should be filled).  You can stop a running script file by pressing the `Stop` button or simply let it continue to run.\n\n![PFxApp](./images/RunScript.png)\n\nTo speed up the iteration of debugging and testing new scripts, you can follow this 4 step process repeatedly for each iteration of your script file:\n\n![Iterate](./images/IterateScripts.png)\n\n## Script Syntax\n\nThe PFx Brick script language syntax is a simple human readable free form text file format. Script files can contain comments and arbitrary amounts of whitespace in addition to the recognized script keywords. Script file execution is sequential and proceeds line by line from the start of the file to the end. This implies that all logical script commands must be terminated with a either a linefeed (`0x0A`) and/or carriage return character (`0x0D`).\n\n### Comments\n\nComment lines start with either a `#` character (similar to python) or `//` characters (similar to C++). Comments should not be used in line with a command.\n\n~~~php\n# Valid comment\n// Another valid comment\nlight 1 on  # not a valid comment location\n~~~\n\n### Keywords\n\nThe script syntax uses case sensitive keyword commands and specifiers.  There are several primary keywords which act as commands and many secondary keywords used for specifying sub-commands, parameters values and options.\n\nThe primary keyword commands are as follows:\n\n~~~php\nlight \u003cchannels\u003e \u003ccommands\u003e\nmotor \u003cchannels\u003e \u003ccommands\u003e\nsound \u003ccommands\u003e\nir \u003cparameters\u003e\nwait \u003cparameters\u003e\nevent\nrepeat\nset \u003cvar\u003e = \u003cvalue\u003e\nset config \u003cvar\u003e = \u003cvalue\u003e\nset file \u003ctype\u003e = \u003cfile\u003e\nrun\nstop\n~~~\n\nThe secondary command and parameter keywords are as follows:\n\n~~~php\nacc, all, bass, beep, ble, brake, bright, button, ch, changedir, config, \nconnect, dec, disconnect, down, fade, file, flash, fx, gated, invert, joy,\nleft, loop, long, off, on, play, rate, right, servo, shutdown, speed, \nstartup, thr, treble, up, usb, vol\n~~~\n\n### Numeric Values\n\nMany commands and options require specified numeric quantities.  The script syntax supports both integer and decimal values.  The following are examples of valid numeric quantities:\n\n~~~php\n0 127 -55 0.010 35.75 -90.5\n~~~\n\nAdditionally, integer values may be specified in hexadecimal (base16) prefixed with the characters `0x`.\n\n~~~php\n0x0 0xABCD 0x32\n~~~\n\n\nFor commands which support a list of values, a list is specified as a group of comma separated numbers enclosed in matching square brackets:\n\n~~~php\n[0, 1, 2, 3]\n~~~\n\n### Strings\n\nSome commands also support the use of strings--typically for specifying items such as filenames.  Strings are UTF-8 formatted and enclosed within double quotations marks (`\"`).\n\n~~~php\n\"This is a string\"\n~~~\n\n### Variables\n\nSix general purpose variable registers can be used to store constants for use in a script.  The variables have the following uppercase names: `$A, $B, $C, $D, $E, $F`.  Use the `set` keyword to assign a variable as follows:\n\n```php\n\nset $A = 0.5\nset $B = 3.0\nset $C = \"Beep.wav\"\nlight 1 on flash $A\nwait $B\nsound play $C\n\n```\n\n### Light Commands\n\n~~~php\nlight \u003cchannels\u003e \u003ccommands\u003e\n~~~\n\n`channels` can be specified as a single channel number 1-8, a list of channels enclosed with\n[] parenthesis, or the keyword all\ncommands are a combination of the following keywords and values: \n\n- `on` - turn on light channel(s)\n- `off` - turn off light channel(s)\n- `fade \u003ctime\u003e` - fade time (0 to 10.0 seconds)\n- `flash \u003contime\u003e[offtime]` - periodic flashing light (0.05 to 60.0 seconds)\n- `bright \u003cvalue\u003e` - set brightness (0 to 255)\n- `fx \u003cid\u003e [parameters]` - performs light `action \u003cid\u003e` as `LIGHT_FX_ID` with specified parameters if `channels` = `all` then `\u003cid\u003e` is a combo id\n\n**Examples:**\n\n~~~php\nlight 1 on\nlight [1,4,8] off fade 0.5\nlight [2,4] flash 0.1 0.4 fade 0.1\nlight all bright 128\nlight [6,7] fx 0x0C [1,0,3,0,0]\n~~~\n\n### Sound Commands\n\n~~~php\nsound \u003ccommand\u003e\n~~~\n\n`command` is one of the following keywords:\n- `play fileID` - start playback of fileID\n- `stop fileID` - stop playback of fileID\n- `play fileID repeat` - continuous playback of fileID \n- `play fileID loop \u003cvalue\u003e` - plays fileID for value times \n- `play fileID random \u003cprobability\u003e` - random playback of fileID \n- `vol \u003cvalue\u003e` - set volume (0 to 255)\n- `bass \u003cvalue\u003e` - set bass (-20 to 20)\n- `beep` - short beep sound\n- `treble \u003cvalue\u003e` - set treble (-20 to 20)\n- `fx fileID \u003cid\u003e[parameters]` - performs sound action \u003cid\u003e as `SOUND_FX_ID` with specified parameters\n\n`fileID` can be specified either as a numeric file ID or string containing the filename.\n\n**Examples:**\n\n```php\nsound play 3 loop 5 \nsound play \"Siren1.wav\" \nsound vol 160\nsound treble -6\nsound fx 9 0x04 0 0\n```\n\n### Motor Commands\n\n~~~php\nmotor \u003cchannels\u003e \u003ccommand\u003e\n~~~\n\n`channels` can be specified as a single channel number 1 or 2 (or as a and b), a list of channels enclosed with [] parenthesis, or the keyword `all`\n\n`command` is one of the following keywords:\n- `stop` - stop motor channel(s)\n- `speed \u003cvalue\u003e` - motor speed (-255 to 255), +speed is forward, -speed is reverse direction\n- `servo \u003cvalue\u003e` - servo motor angle (-90 to 90)\n- `fx \u003cid\u003e [parameters]` - performs motor `action \u003cid\u003e` as `MOTOR_FX_ID` with specified parameters\n\n**Examples:**\n\n~~~php\nmotor all stop\nmotor a speed -50\nmotor 2 servo 45 \nmotor 1 fx 0x07 0x03 0\n~~~\n\n### IR Commands\n\n- `ir on` - activates the IR sensor\n- `ir off` - disables the IR sensor\n\n### Execution Control\n\nDelay execution and wait for event to resume:\n\n- `wait \u003ctime\u003e` - pause (0.05 to unlimited sec)\n- `wait sound fileID` - pause execution until sound file `fileID` has stopped playing\n- `wait ir \u003cparameters\u003e` - pause execution until IR event has been received\n\nwhere `parameters` can be any combination of:\n\n- `joy` - joystick remote, \n- `speed` - speed remote, \n- `up, down, left, right, button` - remote actions \n- `ch \u003cvalue\u003e` - IR channel\n\nRedirect execution to same or different script:\n\n- `repeat` - repeat execution of current script \n- `run fileID` - execute script with fileID\n- `stop` - stops the script at the current line\n\nNesting looping:\n- `repeat \u003cn\u003e { ... }`\n\n**Examples:**\n\n~~~php\nwait 3.0\nwait sound 5\nwait ir joy left up\nwait ir speed ch 4 left button stop\nrun 3\nrun \"MyScript.txt\"\n\nrepeat 3 {\n    repeat 2 {\n        light 1 on\n        wait 0.5\n        light 1 off\n    }\n    light 2 on\n    wait 1\n    light 2 off\n}\n~~~\n\n## Sample Scripts\n\n```php\n# Traffic light sequence\n#\n# Ch 1: Red, Ch 2: Yellow, Ch 3: Green \n# Ch 4: Don't Walk, Ch 5: Walk\n\n# set IR action to turn lights off\nevent ir joy ch 1 left up {\n    light all off\n}\n# set IR action to run this script\nevent ir joy ch 1 left down {\n    run \"traffic_light.pfx\"\n}\n\n# set A to represent the dwell phase\nset $A = 8.0\n# set B to represent the flashing crosswalk phase\nset $B = 5.0\n# set C to represent the yellow phase\nset $C = 4.0\n\n# reset all light channels\nlight all off\n\n# run through the sequence 5 times\nrepeat 5 {\n    # Red phase\n    light [1, 4] on\n    light [2, 3, 5] off fade 0.2 \n    wait $A\n    # Green phase\n    light [1, 4] off fade 0.2\n    light [3, 5] on\n    wait $A\n    # Pedestrian crossing warning \n    light 5 off fade 0.1\n    light 4 flash 0.4 fade 0.1 \n    wait $B\n    # Yellow\n    light 3 off fade 0.2\n    light [2, 4] on\n    wait $B\n}\n```\n\n```php\n# Motorized musical procession\n#\n# Vehicle with motor, lights and music; Triggered by IR remote\n\n# Start with everything off\nlight all off\nsound stop all \nmotor all off\n\n# Wait for joystick remote ch 1 right up\nwait ir joy ch 1 right up\n\n# Play sound and move\nmotor a speed 30\nlight all on\nsound play \"MySong.wav\"\n\n# Wait until song is finished, stop and repeat\nwait sound \"MySong.wav\" \nmotor a stop\nrepeat\n```\n\n\n## References\n\n* [PFx Brick Interface Control Document (ICD) v.3.37](https://github.com/fx-bricks/pfx-brick-dev/raw/master/doc/ICD/PFxBrickICD-Rev3.37.pdf) describes details of PFx Brick operation and communication protocol\n\n* [brickelectronic.de](http://brickelectronic.de) has kindly contributed a custom [PFx language profile for Notepad++](https://github.com/Brickelectronic/pfxbrick_notepadplusplus) available from their Github repository.\n\nIf you want to learn more about PFx Brick, check out [our website](https://fxbricks.com/pfxbrick).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffx-bricks%2Fpfx-brick-vscode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffx-bricks%2Fpfx-brick-vscode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffx-bricks%2Fpfx-brick-vscode/lists"}