! NavCoder Scripting File (*.nsf) ! File Format and Syntax ! ! Version 1.0.1 December 2023 ! ! INTRODUCTION ! The NavCoder scripting capabilities allows you to send responses to datagrams ! received, and to generate datagram messages on timed events. ! This is especially useful for testing ibus devices on the workbench ! or for testing functionality of devices in the vehicle. ! If you run NavCoder on a car PC, you can add extra functions to your vehicle ! e.g.: display some text in the IKE when the ignition is switched on. ! ! ! GENERAL SCRIPT FILE FORMAT RULES ! Any line starting with ! / ; or ' is a comment and ignored. ! Any empty line is ignored. ! Any text following a ' is a comment and ignored. ! The script commands are case insensitive (e.g.: lower and UPPER case are the same) ! There is no text file line length limit (apart from that imposed by Windows) ! NavCoder script files have the .nsf extension (nsf = NavCoder Script File) ! Script files are located in the \Scripting\ folder under the NavCoder.exe folder ! ! ! AUTO LOAD OF A SCRIPT FILE ! If NavCoder is started with a -sf parameter, then ! will be loaded on startup, and automatically enabled. ! A space must exist between -sf and the filename. ! NavCoder first looks for the script file in the App.Path (the folder where ! NavCoder.exe is located) and then, if not found, in App.Path\Scripting\. ! If no -sf flag is specified, then NavCoder tries to load "_Default.nsf", again ! looking first in App.Path and then App.Path\Scripting\. ! ! Example 1: NavCoder.exe -sf "\Scripting\MyScript.nsf" ! This loads MyScript.nsf in the subfolder \Scripting\ located underneath NavCoder.exe. ! ! Example 2: NavCoder.exe -sf "AnotherScript.nsf" ! This loads the file AnotherScript.nsf located in the same folder as NavCoder.exe ! ! Example 3: NavCoder.exe ! This loads the default script file "\Scripting\_Default.nsf", if it exists. ! ! If the script file does not exist, no error is raised. ! If an error occurs reading the script file, it is displayed, and the script is unloaded. ! ! ! PROCESSING A SCRIPT FILE ! When an Event occurs - either a ComEvent because a databus message was received, ! or a TmrEvent because a timer fired, or a LoadEvent because a script was loaded - ! NavCoder loops through all script items to determine what items are active and what ! needs to happen. ! This means - for ComEvents - that the script items are checked on EVERY ibus message received. ! So keep the script files small: large script files will have a performance impact, depending ! on the speed of your PC. ! All messages to Send are added to a SendQueue, to be sent later, once NavCoder has finished ! processing the current task (normally it is working on a received message). ! The messages in the SendQueue are then sent one after the other when the bus has been idle ! for at least 20ms (a collision avoidance mechanism). ! The bus idle time is checked before sending each and every message in the SendQueue. ! This means that generally, 20ms will exist between messages being sent by NavCoder. ! ! ! script KEYWORDS ! OnComEvent() - On an ibus ComEvent execute the following commands ! OnTmrEvent() - On a timed TmrEvent execute the following commands ! OnLoadEvent() - On a script load event execute the following commands ! AppActivate() - [optional] Activate the specified Windows program ! Beep - [optional] Generate a Beep on the PC. ! Load() - [optional] Load a replacement script file ! Logging() - [optional] Enable or disable Logging ! Popup() - [optional] Display a popup window with specified text ! Quit - [optional] Stop execution of the current script file ! Run() - [optional] Run a Windows program ! Send() - [optional] Send a datagram ! SendKey() - [optional] Send keystrokes to the active Windows program ! Stop - [optional] Stop execution of the current script line ! Unload - [optional] Stop execution and unload entire script ! Wait() - [optional] wait for a specified period of time ! ! KEYWORD EXECUTION ORDER ! The OnxxxEvent keyword (OnComEvent, OnTmrEvent, OnLoadEvent) must be the first keyword on ! each line. After the OnxxxEvent keyword, the keywords can exist in any order. ! Execution occurs sequentially. ! OnxxxEvent is mandatory, if it does not exist the script line is ignored. ! All other keywords are optional. ! ! ! KEYWORDS ! ! OnComEvent([],[Srce=],[Dest=],[Cmd=],[Data=]) ! Watch for the specified complete msg or Srce/Dest/Cmd/Data ! When the event occurs, execute the next command on the script line ! Note: msg has precedence over Srce,Dest,Cmd,Data ! If Msg exists, Srce,Dest,Cmd,Data are ignored ! ****** NOTE: Srce,Dest,Cmd,Data not yet implemented!! ****** ! ! OnTmrEvent(Tmr=) ! When the specified timer number fires, execute the next commands ! on the script line. ! The Timer must have been previously enabled with the Timer() command ! after an OnComEvent event ! Note: if no timer number is specified, nbr defaults to 0 (Tmr0). ! ! OnLoadEvent() ! When the script file is loaded, execute the next commands on the script ! line. This event can only happen once, after the script has loaded. ! It is intended to be used as a means of sending commands once only when ! NavCoder starts up the first time, e.g. in a car PC scenario. ! At NavCoder startup, the script is run as the very last item in the ! startup sequence, just after NavCoder appears on screen. ! Multiple OnLoadEvents are possible in the same script file, they are ! executed in order from first to last. ! ! AppActivate() ! Activate the specified Windows program. ! Title is a string containing the title of the application (as it ! appears in the title bar) or the application's Process ID. ! Title = "%NavCoder" sets the title to NavCoder's current title ! to reliably bring NavCoder to the foreground. ! ! Beep ! Generate an audible beep on the Windows PC. ! Intended to assist in checking if scripts are working. ! ! Load(<file>) ! Stops and unloads the existing script file, and then loads a new ! script file. All script commands after the Load command are ! ignored. ! NavCoder first looks for the new script file in the NavCoder.exe ! folder, and then if not found, in the \Scripting\ folder underneath ! NavCoder.exe ! A full filename e.g. C:\Dir\Subdir\filename.ext is also possible ! If the file is not found, an error is displayed when the script ! is first loaded, and also when executing the script. ! ! ! Logging(<state>) ! Enables or disables Logging according to the specified state. ! ! Popup(<text>) ! Displays text in a Windows pop-up message box. ! The box remains onscreen until the user clicks OK. ! The title of the message box is always "NavCoder Script Host" ! ! Quit ! Forces script execution to stop at any time. ! All following script commands in the same script file are ignored. ! ! Run(<program>) ! Run the specified Windows program. ! If the program does not exist or is not found, no error occurs ! uses the Windows Scripting WshShell object and Run method. ! ! Send(<msg>) ! Send the specified msg to the databus. No syntax checking occurs. ! ! sendKeys(<keys>) ! Sends the specified keys to the current Windows program. ! Use Run to ensure the desired program has the focus. ! uses the Windows Scripting WshShell object and SendKeys method. ! Specification of the keys string is here: ! http://msdn.microsoft.com/en-us/library/8c6yea83(v=VS.85).aspx ! ! Stop ! Stop executing the current script line. ! All following script commands on the same line are ignored. ! ! Timer(<state>,[Index=<value>],[Interval=<time_ms>]) ! Set the Timer state to On or Off ! If setting to On, the Interval must be specified in milliseconds. ! An optional timer Index can be specified if you wish to use multiple ! timers. If Index is not supplied, then Index=0 (i.e.: Timer0 is used). ! The Timer is best used to generate script events on a timed basis, ! e.g.: Sending a Device Status Ready every 30s ! ! Unload ! Unload and exit scripting. ! After this command, no more scripting can occur. ! All following script commands in the same script file are ignored. ! ! Wait(<time_ms>) ! Wait for the specified time (in milliseconds) before executing the next ! script command on the same line. ! The Wait is asynchronous, NavCoder keeps on operating during the Wait. ! The wait applies only to the current script line, following lines are not ! affected. ! ! ! PARAMETERs: ! <adr> A string that can be interpreted as an ibus address. ! The parameter can be hex, decimal or the device name. ! Any text in "" can be hex or a device name ! If the text can be interpreted as hex or a device name ! i.e.: "AB" (Airbag or 0xAB), then the hex value is used ! Values are always hex, unless identified as decimal (e.g.: 127d) ! Following are all valid examples of the same device address: ! "NAV" "7F" 0x7F &H7F #7F &7F 7Fh 7F 127d ! ! <byte> A string that can be interpreted as a byte. ! The same interpretation rules apply as for <adr> ! Following are all valid examples of the same value: ! 0x3A &H3A #3A &3A "3A" 58 ! ! <data> A string of bytes, in hex format, separated with a space and ! enclosed in quotation marks. ! Following is a valid data segment: ! "01 02 20 0C" ! ! <file> A string that can be interpreted as a filename, enclosed in quotes "". ! All normal filename rules apply. ! Following are examples of a valid filename: ! "myFilename.txt" "C:\Filename.txt" ! ! <keys> A string of key strokes, as specified by the Windows SendKeys ! method. Refer to Microsoft documentation on SendKeys: ! http://msdn.microsoft.com/en-us/library/8c6yea83(v=VS.85).aspx ! Following is a valid data key sequence: ! "Hello from NavCoder" - this text is send as keystrokes ! "%F" - the keystroke Alt-F ! ! <msg> A fully-formed datagram, in hex format, separated with spaces ! and enclosed in quotation marks. ! Note: Use same format as displayed in NavCoder log files. ! Following is a valid datagram: ! "80 04 BF 11 01 2B" ! ! <program> A Windows program. Can be either the full filename or a valid ! shortcut that Windows accepts. ! Following are both valid examples of the program name for Windows Notepad: ! "notepad" "C:\Windows\notepad.exe" ! ! <state> A boolean value of either On or Off. Any text that is not On, is ! interpreted as off. ! Following is a valid value for On resp. Off: ! On Off ! ! <time_ms> A value in the range 1 to 65535, representing milliseconds ! Following is a valid timer value for 1.5 seconds: ! 1500 ! ! <title> A string containing the title of the Windows application (as it appears ! in the title bar) or the application's Process ID. Used with AppActivate ! to activate the Windows program. ! Following is a valid example of the program name for Windows Notepad ! "notepad" "C:\Windows\notepad.exe" ! Use Title = "%NavCoder" to set the title to NavCoder's current title ! and thus reliably bring NavCoder to the foreground. ! ! <text> A plain text string, enclosed in quotes "" ! Following is a plain text string to display "Hello World": ! "Hello World" ! ! <value> A value that can be interpreted as a long integer. ! decimal places are ignored. ! Following is a value of 255: ! 255 ! Example 1 ! This example displays the text "Hello World" in the IKE 1 second after the IKE advises the ign is in Pos1 ! OnComEvent(Srce=IKE,Dest=GLO,Cmd=0x11) Wait(1000) Send("30 19 80 1A 37 0F 20 20 20 20 48 65 6C 6C 6F 20 57 6F 72 6C 64 20 20 20 20 20 8B") ! The same example using the entire ibus msg as the key ! OnComEvent(Msg="80 04 BF 11 01 2B") Wait(500) Send("30 19 80 1A 37 0F 20 20 20 20 48 65 6C 6C 6F 20 57 6F 72 6C 64 20 20 20 20 20 8B") ! OnComEvent(Msg="80 04 BF 11 01 2B") Wait(200) Send("30 19 80 1A 37 0F 20 20 20 20 48 65 6C 6C 6F 20 57 6F 72 6C 64 20 20 20 20 20 8B") ! OnComEvent BMBT --> RAD : Device status request ! Send RAD --> GLO : Device status ready OnComEvent(Msg="F0 03 68 01 9A") Wait(300) Send("68 04 BF 02 00 D1") ! OnComEvent CCM --> GLO : Checkcontrol sensors: Key_in_Ignition ! Send CCM --> IKE : IKE Text/Gong, " Msg Detected! " Clear Gong_off Warning_symbol_off OnComEvent(Msg="30 04 BF 51 04 DE") Wait(1) Send("30 14 80 1A 37 0F 20 4D 73 67 20 44 65 74 65 63 74 65 64 21 20 F8") !OnComEvent(Msg="30 04 BF 51 04 DE") Wait(1000) Send("30 14 80 1A 37 0F 20 4D 73 67 20 44 65 74 65 63 74 65 64 21 20 F8")