api-webserver README

This extension make it possible to take control of Arduino IDE from a Web Page based client. It also have a WebSocket server that is used for midi comms.

Install

• global:
    download this repository by either Code-Download Zip or
      by git clone https://github.com/manicken/arduinoAPIwebserver.git
    then extract/open the repository
  

• global (into sketchbook folder (defined in Arduino IDE - Preferenses):
    make a new folder in the above defined sketchbook folder
    called tools
    then copy folder API_WebServer from the repository into this new "tools" folder.
  

Alternative install

• on windows / linux (into Arduino IDE install dir):
    copy folder API_WebServer to [Arduino IDE install location]/tools directory
    ex: /Arduino-1.8.13/tools
  

• on mac (into Arduino IDE package):
    In Applications right click and click on "Show Package Contents", then browse Contents -> Java -> tools
    by holding the Option key(copy) drag folder API_WebServer from the downloaded repository to the open tools folder above
    select replace it you allready have an older version
  

Compiling

Download and Install Java SDK8 (1.8) 32bit
(Arduino IDE uses Java 8 (1.8))

two script is provided:
  for windows the .bat file
  for linux/mac the .sh file

Features

POST request with data contents in json format:

{
    "files":[
        {
            "name":"Main.c",
            "contents":""
            "overwrite_file": true
        },
        {
            "name":"Main.h",
            "contents":""
            "overwrite_file": true
        }
    ],
    "removeOtherFiles":true,
    "keywords":[
        {
            "token":"MainClass",
            "type":"KEYWORD2"
        },
        {
            "token":"SecondClass",
            "type":"KEYWORD2"
        },
        {
            "token":"SomeConstantVariable",
            "type":"LITERAL1"
        }
    ]
}

in above json:
removeOtherFiles
 mean that when this is set to true
 then files that is not present in the JSON is removed
 from the sketch (note. the main sketch file is never removed)
 if the main sketch file also should be replaced then a file named main.cpp should be present in the JSON
 example when it should be set to false:
 when only some permanent files needs to be updated ex. the JSON file.

overwrite_file
 mean that when this is set to true
 the destination file is overwritten with the contents given
 when set to false
 this is useful together with removeOtherFiles set to true
 when having files in the sketch that should not be deleted
 i.e. big source files that contain huge binary data arrays

 keywords uses the same naming as keywords.txt

 POST JSON the three main objects "files", "removeOtherFiles" and "keywords" is optional
 but the removeOtherFiles is allways used together with "files"

GET request

possible query strings:

http://localhost:8080?cmd=getFile&fileName=fileNameWithExt
http://localhost:8080?cmd=renameFile&from=fromNameWithExt&to=toNameWithExt
http://localhost:8080?cmd=removeFile&fileName=fileNameWithExt
http://localhost:8080?cmd=compile
http://localhost:8080?cmd=upload
http://localhost:8080?cmd=ping

• uses sketch location keywords.txt for additional custom keywords
  

Midi WebSocketServer Bridge

Just as the title say, it's a WebSocket Server that is bridged with midi input and output devices
(all received commands are converted to lowercase before parsing)
accepts the following commands:

• midisend(0x90, 60, 0x3F)    the parameters can be mixed hexadecimal (0x) & decimal
  
• midigetdevices    this sends back two messages:
                  midiDevicesIn("device1", "device2", "device3)
                  midiDevicesOut("device1", "device2", "device3)
  
• midisetdevicein(0)    sets and connects the in device with index 0
  
• midisetdeviceout(0)    sets and connects the out device with index 0
  

Midi WebSocketServer Bridge - standalone (same functionality as above Midi WebSocketServer Bridge)

the jar is executable in standalone mode
with only the MidiWebSocketBridge active

this can be used when using the VSCODE extension
because the VSCODE (Node.js) have no native support for midi devices.

in this mode it have the following parameters:
listdevices (list midi devices) just to quick check connected devices.
port 3001 (starts the websocket server at port 3001)

Requirements

Java-WebSocket-1.5.1.jar (included) from [Java-WebSocket](https://github.com/TooTallNate/Java-WebSocket)
json-20200518.jar (included) from [JSON-Java](https://github.com/stleary/JSON-java)

Extension Settings

Known Issues

when using terminal capture and send (allways on in this version)<br>
and using compile output with alot of data the data sent to client is alot after<br>
and continues to output long after compilation is finished.<br>
Fix is to not use compile output log. The result is allways printed.<br>

Release Notes

1.0.0

Initial release of API_Webserver

1.0.1

Add GET and POST requests

1.0.2

Add Settings file

1.0.3

Add terminal capture and send to connected WebSocket client

1.0.4

• Add POST JSON data removeOtherFiles
  
• Fix File write flag so that it overwrites existing files
  

1.0.5

• Add sketch location keywords.txt file
• Add POST JSON data keywords that also save to sketch location keywords_temp.txt
• in POST JSON the three main objects "files", "removeOtherFiles" and "keywords" is optional

1.0.6

• Splitted out classes from API_Webserver.java
• ConfigDialog.java
• MyConsoleOutputStream.java (not currently used) replaced by simpler System.out hook
• MyHttpHandler.java
• MyWebSocketServer.java
• AutoCompleteProvider.java
      finally Arduino IDE gets autocomplete (experimental)
      can be activated on Tools-API Web Server-activate autocomplete
      define file is in tool dir of API_WebServer called c.xml
      (later this is getting a seperate repository as additional plugin)
  

1.0.7

Created new classes

• CustomMenu.java
• IDEhelper.java
• Reflect.java // static reflect helper methods
• MyConsoleOutputStream.java is now used again (but currently not working)

1.0.8

Created new class

• MidiHelper.java

added "overwrite_file" parameter to JSON post file

1.0.9

Created new classes

• MidiWebSocketBridge.java
• Main.java (making this jar standalone executable used by MidiWebSocketBridge) supports exec. arguments:
  listdevices (list midi devices)
  port 3001 (starts the websocket server at port 3001)
  

1.1.0

• Removed AutoCompleteProvider.java moved to new repository https://github.com/manicken/arduinoAutoComplete

---