From c2cbc19451639667ed2395b14e6ac9e92b88a598 Mon Sep 17 00:00:00 2001 From: Jitpanu Maneeratpongsuk Date: Tue, 20 Jan 2026 19:50:17 +0000 Subject: [PATCH 01/12] Add gateway node-type documentation --- docs/node/nodes/gateway.md | 116 +++++++++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 docs/node/nodes/gateway.md diff --git a/docs/node/nodes/gateway.md b/docs/node/nodes/gateway.md new file mode 100644 index 00000000..adecf28e --- /dev/null +++ b/docs/node/nodes/gateway.md @@ -0,0 +1,116 @@ +--- +sidebar_label: Gateway +hide_table_of_contents: true +--- + +# Gateway + +The `gateway` node-type enable VILLASnode to transform api type. +Currently, the transformation of [http](https://en.wikipedia.org/wiki/HTTP) and [gRPC](https://grpc.io/) is supported. + + +### Limitations + +- For protobuf payload that is not [VILLASnode format](../formats/protobuf.md), only simple datatypes are supported. +- It only supported unary RPC. + + +## Prerequisites + +This node-type requires [gRPC](https://grpc.io/) and [reflection.proto](https://github.com/grpc/grpc/blob/master/src/proto/grpc/reflection/v1alpha/reflection.proto) for gRPC server [reflection](https://grpc.io/docs/guides/reflection/). +The script `packaging/deps.sh` can be used to automatically download reflection.proto and generate protobuf code. +Please refer to the [installation document](../installation.md). + +## Implementation + +The source code of the node-type is available here: +https://github.com/VILLASframework/node/blob/master/lib/nodes/gateway.cpp + +## Configuration {#config} + +import ApiSchema from '@theme/ApiSchema'; + + + +## Example + +``` url="external/node/etc/examples/nodes/gateway.conf" title="node/etc/examples/nodes/api.conf" +http = { + port = 8080 +} + +nodes = { + gateway_node = { + type = "gateway" + + format = "protobuf" + # API type + gateway_type = "gRPC" + # Address of remote server + address = "localhost:50051" + } +} +``` + +## Usage + +The usage of this node is similar to [`api`](api.md) node-type. +The following [`curl`](https://curl.se/) commands are example for calling gRPC method with HTTP api. +The input of gRPC method can be either by the body of http request or input data from other node(via a [path](../config/paths.md)). +If the http request body is empty, the input from other node will be used. + +Note on http methods + - GET should be used only when the input of gRPC method can be empty or ignored. + - PUT should be used when the output of gRPC method is in VILLASnode format and the user want to put the data to the path. + - POST should be used when the output of gRPC method is not in VILLASnode format or the user not want output data to the path. + + +#### The url for sending a request to this node-type are as following +``` +http://
:/api/v2/gateway//// +``` + +The following `.proto` file will be used as an example +``` +syntax = "proto3"; + +import "villas.proto"; + +package ex_server; + +service ex_service { + rpc GetData (villas.node.Message) returns (villas.node.Message) {}; + rpc SetData (villas.node.Message) returns (msg) {}; + rpc GetDataRef (Reference) returns (villas.node.Message) {}; +} + +message Reference { + repeated int32 ref = 1; +} + +message msg { + string status = 1; +} + +``` + +#### Call GetData method on gRPC server + +```shell +curl http://localhost:8080/api/v2/gateway/gateway_node/ex_server/ex_service/GetData -XPUT +``` +Since the PUT method is used, the output from gRPC method will be put to the path. + +#### Call SetData method on gRPC server + +```shell +curl http://localhost:8080/api/v2/gateway/gateway_node/ex_server/ex_service/SetData -XPOST +``` +Since the body is empty the data from the path will be send to gRPC server. + +#### Call GetDataRef method on gRPC server + +```shell +curl http://localhost:8080/api/v2/gateway/gateway_node/ex_server/ex_service/GetDataRef -d '{"ref":[0,1,2,3,4]}' +``` +Since the body is not empty, it will be form into protobuf payload based on the example `.proto` file and send to the gRPC server. From 1236b036c5b9c0e59eede1ed43a9a0852dcf63a2 Mon Sep 17 00:00:00 2001 From: Alexandra Date: Tue, 27 Jan 2026 08:09:49 +0000 Subject: [PATCH 02/12] Add gateway node docu Co-authored-by: Jitpanu Maneeratpongsuk Signed-off-by: Alexandra --- docs/node/nodes/gateway.md | 21 ++++++++++++--------- docs/node/nodes/index.md | 1 + 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/node/nodes/gateway.md b/docs/node/nodes/gateway.md index adecf28e..914d4f54 100644 --- a/docs/node/nodes/gateway.md +++ b/docs/node/nodes/gateway.md @@ -5,14 +5,14 @@ hide_table_of_contents: true # Gateway -The `gateway` node-type enable VILLASnode to transform api type. +The `gateway` node-type enables VILLASnode to transform Application Programmable Interfaces (API) types. Currently, the transformation of [http](https://en.wikipedia.org/wiki/HTTP) and [gRPC](https://grpc.io/) is supported. ### Limitations - For protobuf payload that is not [VILLASnode format](../formats/protobuf.md), only simple datatypes are supported. -- It only supported unary RPC. +- It only supportes unary RPC. ## Prerequisites @@ -55,17 +55,20 @@ nodes = { ## Usage The usage of this node is similar to [`api`](api.md) node-type. -The following [`curl`](https://curl.se/) commands are example for calling gRPC method with HTTP api. -The input of gRPC method can be either by the body of http request or input data from other node(via a [path](../config/paths.md)). +The following [`curl`](https://curl.se/) commands are examples for calling gRPC methods with http API. +The input for a gRPC call can be either the body of http request or input data from another node (via a [path](../config/paths.md)). If the http request body is empty, the input from other node will be used. +Since this node-type does not implement the gRPC server, it needs to be added manually. A description is available [here](https://www.acs.eonerc.rwth-aachen.de/global/show_document.asp?id=aaaaaaaadidaesd). + Note on http methods - GET should be used only when the input of gRPC method can be empty or ignored. - PUT should be used when the output of gRPC method is in VILLASnode format and the user want to put the data to the path. - POST should be used when the output of gRPC method is not in VILLASnode format or the user not want output data to the path. -#### The url for sending a request to this node-type are as following +### General Request +The url for sending a request to the gateway node-type is as following: ``` http://
:/api/v2/gateway//// ``` @@ -94,23 +97,23 @@ message msg { ``` -#### Call GetData method on gRPC server +### Call GetData method on gRPC server ```shell curl http://localhost:8080/api/v2/gateway/gateway_node/ex_server/ex_service/GetData -XPUT ``` Since the PUT method is used, the output from gRPC method will be put to the path. -#### Call SetData method on gRPC server +### Call SetData method on gRPC server ```shell curl http://localhost:8080/api/v2/gateway/gateway_node/ex_server/ex_service/SetData -XPOST ``` Since the body is empty the data from the path will be send to gRPC server. -#### Call GetDataRef method on gRPC server +### Call GetDataRef method on gRPC server ```shell curl http://localhost:8080/api/v2/gateway/gateway_node/ex_server/ex_service/GetDataRef -d '{"ref":[0,1,2,3,4]}' ``` -Since the body is not empty, it will be form into protobuf payload based on the example `.proto` file and send to the gRPC server. +Since the body is not empty, it will a protobuf payload based on the example `.proto` file and send to the gRPC server. diff --git a/docs/node/nodes/index.md b/docs/node/nodes/index.md index d0718a4c..69fc86f7 100644 --- a/docs/node/nodes/index.md +++ b/docs/node/nodes/index.md @@ -27,6 +27,7 @@ VILLASnode currently supports the following node-types: | [exec](exec.md) | no | yes | yes | unlimited | stable | | | [file](file.md) | no | yes | yes | unlimited | stable | | | [fpga](fpga.md) | no | yes | yes | ? | beta | | +| [gateway](gateway.md) | no | yes | yes | unlimited | stable | HTTP to gRPC conversion only | | [iec60870-5-104](iec60870-5-104.md) | no | no | yes | 1 | stable | | | [iec61850-8-1](iec61850-8-1.md) | no | yes | yes | 1 | alpha | | | [iec61850-9-2](iec61850-9-2.md) | no | yes | yes | 1 | beta | | From 0ea4ec88100a5f00a1ba2bed780071073fe9e9d8 Mon Sep 17 00:00:00 2001 From: al3xa23 <140614263+al3xa23@users.noreply.github.com> Date: Mon, 30 Mar 2026 12:14:05 +0200 Subject: [PATCH 03/12] Update docs/node/nodes/gateway.md Co-authored-by: Steffen Vogel Signed-off-by: al3xa23 <140614263+al3xa23@users.noreply.github.com> --- docs/node/nodes/gateway.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/node/nodes/gateway.md b/docs/node/nodes/gateway.md index 914d4f54..163984de 100644 --- a/docs/node/nodes/gateway.md +++ b/docs/node/nodes/gateway.md @@ -55,7 +55,7 @@ nodes = { ## Usage The usage of this node is similar to [`api`](api.md) node-type. -The following [`curl`](https://curl.se/) commands are examples for calling gRPC methods with http API. +The following [`curl`](https://curl.se/) commands are examples for calling gRPC methods via the HTTP API. The input for a gRPC call can be either the body of http request or input data from another node (via a [path](../config/paths.md)). If the http request body is empty, the input from other node will be used. From 2bbf18fa7721da21e3e7b8e8169020e8bd01d2b7 Mon Sep 17 00:00:00 2001 From: al3xa23 <140614263+al3xa23@users.noreply.github.com> Date: Mon, 30 Mar 2026 12:14:24 +0200 Subject: [PATCH 04/12] Update docs/node/nodes/gateway.md Co-authored-by: Steffen Vogel Signed-off-by: al3xa23 <140614263+al3xa23@users.noreply.github.com> --- docs/node/nodes/gateway.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/node/nodes/gateway.md b/docs/node/nodes/gateway.md index 163984de..6ad83f4b 100644 --- a/docs/node/nodes/gateway.md +++ b/docs/node/nodes/gateway.md @@ -56,7 +56,7 @@ nodes = { The usage of this node is similar to [`api`](api.md) node-type. The following [`curl`](https://curl.se/) commands are examples for calling gRPC methods via the HTTP API. -The input for a gRPC call can be either the body of http request or input data from another node (via a [path](../config/paths.md)). +The input for a gRPC call can be either the body of HTTP request or input data from another node (via a [path](../config/paths.md)). If the http request body is empty, the input from other node will be used. Since this node-type does not implement the gRPC server, it needs to be added manually. A description is available [here](https://www.acs.eonerc.rwth-aachen.de/global/show_document.asp?id=aaaaaaaadidaesd). From 5de12d384f15ee33bd899d1834e0bd44272b7f84 Mon Sep 17 00:00:00 2001 From: al3xa23 <140614263+al3xa23@users.noreply.github.com> Date: Mon, 30 Mar 2026 12:14:47 +0200 Subject: [PATCH 05/12] Update docs/node/nodes/gateway.md Co-authored-by: Steffen Vogel Signed-off-by: al3xa23 <140614263+al3xa23@users.noreply.github.com> --- docs/node/nodes/gateway.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/node/nodes/gateway.md b/docs/node/nodes/gateway.md index 6ad83f4b..3f2d36d9 100644 --- a/docs/node/nodes/gateway.md +++ b/docs/node/nodes/gateway.md @@ -68,6 +68,7 @@ Note on http methods ### General Request + The url for sending a request to the gateway node-type is as following: ``` http://
:/api/v2/gateway//// From 9d1963bd3dd264edcc4853dfbdfdf1f509ac822c Mon Sep 17 00:00:00 2001 From: al3xa23 <140614263+al3xa23@users.noreply.github.com> Date: Mon, 30 Mar 2026 12:14:58 +0200 Subject: [PATCH 06/12] Update docs/node/nodes/gateway.md Co-authored-by: Steffen Vogel Signed-off-by: al3xa23 <140614263+al3xa23@users.noreply.github.com> --- docs/node/nodes/gateway.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/node/nodes/gateway.md b/docs/node/nodes/gateway.md index 3f2d36d9..29a5b132 100644 --- a/docs/node/nodes/gateway.md +++ b/docs/node/nodes/gateway.md @@ -69,7 +69,7 @@ Note on http methods ### General Request -The url for sending a request to the gateway node-type is as following: +The URL for sending a request to the gateway node-type is as following: ``` http://
:/api/v2/gateway//// ``` From 40b0a5e2cb9b5ff383825dc92a3e045feb1109b2 Mon Sep 17 00:00:00 2001 From: al3xa23 <140614263+al3xa23@users.noreply.github.com> Date: Mon, 30 Mar 2026 12:15:10 +0200 Subject: [PATCH 07/12] Update docs/node/nodes/gateway.md Co-authored-by: Steffen Vogel Signed-off-by: al3xa23 <140614263+al3xa23@users.noreply.github.com> --- docs/node/nodes/gateway.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/node/nodes/gateway.md b/docs/node/nodes/gateway.md index 29a5b132..a13e034f 100644 --- a/docs/node/nodes/gateway.md +++ b/docs/node/nodes/gateway.md @@ -98,7 +98,7 @@ message msg { ``` -### Call GetData method on gRPC server +### Call `GetData` method on gRPC server ```shell curl http://localhost:8080/api/v2/gateway/gateway_node/ex_server/ex_service/GetData -XPUT From 22c7201ddaf34d8b2e8e4ef7272a4d885039a6c3 Mon Sep 17 00:00:00 2001 From: al3xa23 <140614263+al3xa23@users.noreply.github.com> Date: Mon, 30 Mar 2026 12:15:24 +0200 Subject: [PATCH 08/12] Update docs/node/nodes/gateway.md Co-authored-by: Steffen Vogel Signed-off-by: al3xa23 <140614263+al3xa23@users.noreply.github.com> --- docs/node/nodes/gateway.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/node/nodes/gateway.md b/docs/node/nodes/gateway.md index a13e034f..41108a22 100644 --- a/docs/node/nodes/gateway.md +++ b/docs/node/nodes/gateway.md @@ -105,7 +105,7 @@ curl http://localhost:8080/api/v2/gateway/gateway_node/ex_server/ex_service/GetD ``` Since the PUT method is used, the output from gRPC method will be put to the path. -### Call SetData method on gRPC server +### Call `SetData` method on gRPC server ```shell curl http://localhost:8080/api/v2/gateway/gateway_node/ex_server/ex_service/SetData -XPOST From 3058233e85757b38532de8f6e2324b369330c59e Mon Sep 17 00:00:00 2001 From: al3xa23 <140614263+al3xa23@users.noreply.github.com> Date: Mon, 30 Mar 2026 12:15:35 +0200 Subject: [PATCH 09/12] Update docs/node/nodes/gateway.md Co-authored-by: Steffen Vogel Signed-off-by: al3xa23 <140614263+al3xa23@users.noreply.github.com> --- docs/node/nodes/gateway.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/node/nodes/gateway.md b/docs/node/nodes/gateway.md index 41108a22..adb75353 100644 --- a/docs/node/nodes/gateway.md +++ b/docs/node/nodes/gateway.md @@ -112,7 +112,7 @@ curl http://localhost:8080/api/v2/gateway/gateway_node/ex_server/ex_service/SetD ``` Since the body is empty the data from the path will be send to gRPC server. -### Call GetDataRef method on gRPC server +### Call `GetDataRef` method on gRPC server ```shell curl http://localhost:8080/api/v2/gateway/gateway_node/ex_server/ex_service/GetDataRef -d '{"ref":[0,1,2,3,4]}' From be25d5d44f2e695d4a9e7e0fb038147ed4d85014 Mon Sep 17 00:00:00 2001 From: al3xa23 <140614263+al3xa23@users.noreply.github.com> Date: Mon, 30 Mar 2026 12:15:47 +0200 Subject: [PATCH 10/12] Update docs/node/nodes/gateway.md Co-authored-by: Steffen Vogel Signed-off-by: al3xa23 <140614263+al3xa23@users.noreply.github.com> --- docs/node/nodes/gateway.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/node/nodes/gateway.md b/docs/node/nodes/gateway.md index adb75353..3318492f 100644 --- a/docs/node/nodes/gateway.md +++ b/docs/node/nodes/gateway.md @@ -61,7 +61,7 @@ If the http request body is empty, the input from other node will be used. Since this node-type does not implement the gRPC server, it needs to be added manually. A description is available [here](https://www.acs.eonerc.rwth-aachen.de/global/show_document.asp?id=aaaaaaaadidaesd). -Note on http methods +Note on HTTP methods - GET should be used only when the input of gRPC method can be empty or ignored. - PUT should be used when the output of gRPC method is in VILLASnode format and the user want to put the data to the path. - POST should be used when the output of gRPC method is not in VILLASnode format or the user not want output data to the path. From 4bd605e819d9031165ffa379c36b99b701864c4a Mon Sep 17 00:00:00 2001 From: al3xa23 <140614263+al3xa23@users.noreply.github.com> Date: Mon, 30 Mar 2026 12:16:03 +0200 Subject: [PATCH 11/12] Update docs/node/nodes/gateway.md Co-authored-by: Steffen Vogel Signed-off-by: al3xa23 <140614263+al3xa23@users.noreply.github.com> --- docs/node/nodes/gateway.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/node/nodes/gateway.md b/docs/node/nodes/gateway.md index 3318492f..844984f4 100644 --- a/docs/node/nodes/gateway.md +++ b/docs/node/nodes/gateway.md @@ -6,7 +6,7 @@ hide_table_of_contents: true # Gateway The `gateway` node-type enables VILLASnode to transform Application Programmable Interfaces (API) types. -Currently, the transformation of [http](https://en.wikipedia.org/wiki/HTTP) and [gRPC](https://grpc.io/) is supported. +Currently, the transformation of [HTTP](https://en.wikipedia.org/wiki/HTTP) and [gRPC](https://grpc.io/) is supported. ### Limitations From f0700975e50920b34757e2085d3063b571eda043 Mon Sep 17 00:00:00 2001 From: Alexandra Date: Mon, 30 Mar 2026 11:25:24 +0000 Subject: [PATCH 12/12] node-gateway: address review Signed-off-by: Alexandra --- docs/node/nodes/gateway.md | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/docs/node/nodes/gateway.md b/docs/node/nodes/gateway.md index 844984f4..08e79b1c 100644 --- a/docs/node/nodes/gateway.md +++ b/docs/node/nodes/gateway.md @@ -5,16 +5,9 @@ hide_table_of_contents: true # Gateway -The `gateway` node-type enables VILLASnode to transform Application Programmable Interfaces (API) types. +The `gateway` node-type enables VILLASnode to translate between Application Programmable Interfaces (API) types. Currently, the transformation of [HTTP](https://en.wikipedia.org/wiki/HTTP) and [gRPC](https://grpc.io/) is supported. - -### Limitations - -- For protobuf payload that is not [VILLASnode format](../formats/protobuf.md), only simple datatypes are supported. -- It only supportes unary RPC. - - ## Prerequisites This node-type requires [gRPC](https://grpc.io/) and [reflection.proto](https://github.com/grpc/grpc/blob/master/src/proto/grpc/reflection/v1alpha/reflection.proto) for gRPC server [reflection](https://grpc.io/docs/guides/reflection/). @@ -26,6 +19,10 @@ Please refer to the [installation document](../installation.md). The source code of the node-type is available here: https://github.com/VILLASframework/node/blob/master/lib/nodes/gateway.cpp +### Limitations + +- The `gateway` node-type only supportes unary RPC. + ## Configuration {#config} import ApiSchema from '@theme/ApiSchema'; @@ -59,14 +56,13 @@ The following [`curl`](https://curl.se/) commands are examples for calling gRPC The input for a gRPC call can be either the body of HTTP request or input data from another node (via a [path](../config/paths.md)). If the http request body is empty, the input from other node will be used. -Since this node-type does not implement the gRPC server, it needs to be added manually. A description is available [here](https://www.acs.eonerc.rwth-aachen.de/global/show_document.asp?id=aaaaaaaadidaesd). +Since this node-type does not implement the gRPC server, it needs to be added manually. A description is available [1]. Note on HTTP methods - GET should be used only when the input of gRPC method can be empty or ignored. - PUT should be used when the output of gRPC method is in VILLASnode format and the user want to put the data to the path. - POST should be used when the output of gRPC method is not in VILLASnode format or the user not want output data to the path. - ### General Request The URL for sending a request to the gateway node-type is as following: @@ -74,7 +70,7 @@ The URL for sending a request to the gateway node-type is as following: http://
:/api/v2/gateway//// ``` -The following `.proto` file will be used as an example +The following `server.proto` file will be used as an example which imports the already existing [`villas.proto`](https://github.com/VILLASframework/node/blob/master/lib/formats/villas.proto) data format. ``` syntax = "proto3"; @@ -99,22 +95,30 @@ message msg { ``` ### Call `GetData` method on gRPC server +The `GetData` method writes the data from gRPC server to the VILLASnode path. +It uses the PUT method. ```shell curl http://localhost:8080/api/v2/gateway/gateway_node/ex_server/ex_service/GetData -XPUT ``` -Since the PUT method is used, the output from gRPC method will be put to the path. ### Call `SetData` method on gRPC server +The `SetData` method writes the data from the VILLASnode path to the gRPC server. +No data is given in the request body. +It uses the POST method. ```shell curl http://localhost:8080/api/v2/gateway/gateway_node/ex_server/ex_service/SetData -XPOST ``` -Since the body is empty the data from the path will be send to gRPC server. ### Call `GetDataRef` method on gRPC server +The `GetDataRef` method requests data of the gRPC based on input references, e.g., referring to nodes in the simulation. +The body provides a protobuf payload based on the example `.proto` file. +VILLASnode send the request to the gRPC server. ```shell curl http://localhost:8080/api/v2/gateway/gateway_node/ex_server/ex_service/GetDataRef -d '{"ref":[0,1,2,3,4]}' ``` -Since the body is not empty, it will a protobuf payload based on the example `.proto` file and send to the gRPC server. + +# Reference +[1] Jitpanu Maneeratpongsuk, "Enhancing Interoperability and Automation in Co-Simulations: An API Gateway Approach for VILLASnode," [Online]. Available: https://www.acs.eonerc.rwth-aachen.de/global/show_document.asp?id=aaaaaaaadidaesd \ No newline at end of file