The Remote Control Server gives you options to create your own Routs, Instructions and scripts to control PCB-Investigator from outside.

In PCB-Investigator you have three buttons:

"Start Server" activate the remote control 

"Stop Server" deactivate the remote control

"Server Settings" shows the settings dialog:

Here you can configurate the comunication port and timeout, you can also manage the available scripts.

What are routes?

Routes are endpoints in a web server that define how to handle incoming requests. They are used to define the behavior of the server when a client makes a request to a specific URL.

Routes can be used to perform actions, return data, or serve files. They are a fundamental part of web development and are used to create APIs, web applications, and more.

In the context of the PCB-Investigator Remote Control Server, routes are used to define the actions that the server can perform. For example, you can create routes to do virtually anything PCB-Investigator itself can, like loading files, running scripts, or exporting data.

How do I add a route?

To add a route, use the PCBI_RemoteControlServer.PCBI_Connection.AddRoute method. It has the following parameters:

verb: The HTTP verb to use for the route. This can be "GET", "POST", "PUT", "DELETE", etc.

path: The part after the base url. This can be a simple route like /load/odb. Dynamic paths like /load/{odb_name} are not supported.

handler: The action to perform when the route is called. This can be a method or a lambda function.

category: The category of the route. This is used to group routes together in the documentation.

description: A description of what the route does. This is used in the documentation.

Example:

IPCBIWindow pcbi; // This is a placeholder. Use your own instance of PCB-Investigator.

async Task LoadODB(HttpListenerContext context) 
{
    const string paramKey = "path";

    var designPath = ctx.Request.QueryString.Get(paramKey);
    if (string.IsNullOrWhiteSpace(designPath))
    {
        ctx.Response.StatusCode = 400;
        return;
    }

    var success = pcbi.LoadData(designPath);

    if (!success)
    {
        ctx.Response.StatusCode = 500;
        return;
    }
}
PCBI_Connection.AddRoute("GET", "/load/odb", LoadODB, "ODB", "Load an ODB file.");
            

This will add a route that listens for GET requests to /load/odb. When a request is received, the LoadODB method will be called. The route will be grouped under the "ODB" category in the documentation, and the description will be "Load an ODB file."

You can add as many routes as you like. Make sure to call PCBI_Connection.StartServer after adding all the routes to start the server.

What are instructions?

Instructions are commands for PCB-Investigator that are queued and executed sequentially. This means they will be executed in the order that they were sent in.
Instructions can be used to automate tasks, such as loading a file, running a script, or exporting data. They are especially useful for automating long-running tasks, because you can queue them and check the status later.

How do I add an instruction?

Adding new available instructions

To add an instruction using the PCBI_RemoteControlServer.PCBI_Connection.AddInstruction method, follow these steps:

1. Understand the Method Signature:

   public void AddInstruction(string name, Func<Entities.RequestDto, Task<Entities.InstructionResult>> handler, string description = "")

   • name: A string representing the name of the instruction.
   • handler: A Func delegate that takes an Entities.RequestDto and returns a Task<Entities.InstructionResult>. This is the function that will be executed when the instruction is called.
   • description: An optional string providing a description of the instruction.
2. Create the Handler Function:

   The handler function should match the signature Func<Entities.RequestDto, Task<Entities.InstructionResult>>. Here is an example of how to create such a function:

   public async Task<Entities.InstructionResult> MyInstructionHandler(Entities.RequestDto request)
   {
       // Your logic here
       var result = new Entities.InstructionResult();
       // Populate result based on the request
       return await Task.FromResult(result);
   }

3. Add the Instruction:

   Use the AddInstruction method to register your new instruction. Here is an example:

   
                       PCBI_RemoteControlServer.PCBI_Connection connection; // This is a placeholder. Get the currenly loaded Plugin instance.
                       connection.AddInstruction("MyInstruction", MyInstructionHandler, "This is a sample instruction.");

4. Example Usage:

   Here is a complete example that demonstrates how to add an instruction:

   
   using System;
   using System.Threading.Tasks;
   using PCBI_RemoteControlServer;
   
   public async Task<Entities.InstructionResult> MyInstructionHandler(Entities.RequestDto request)
   {
       var result = new Entities.InstructionResult();
       // Implement your logic here
       return await Task.FromResult(result);
   }
   
   public void RegisterInstruction()
   {
       PCBI_RemoteControlServer.PCBI_Connection connection; // This is a placeholder. Get the currenly loaded Plugin instance.
       connection.AddInstruction("MyInstruction", MyInstructionHandler, "This is a sample instruction.");
   }
                   

Adding an instruction to the queue

Once an instruction is made available, it can be queued with the HTTP request POST /instructions described on the homepage.

What are scripts?

Scripts are sequences of instructions that automate tasks in PCB-Investigator. They can be used to perform complex operations, such as data analysis, file manipulation, and more.

How do I add a script?

Scripts can be added in PCB-Investigator in the `URI Editor` of this plugin.
There you will also find an example script.

Executing a script

Once a script is registered, it can be executed with the script-instruction.