From 1acb91f44a83529d7cd6ee5c8a2efc512bc0ed7d 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 Signed-off-by: Alexandra --- 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 da1b3bdfcbc4ac7599e89fabf883798bdd035054 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 56f42799e7d3ee39ac42cbcaf7f5999baca3e29b 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> Signed-off-by: Alexandra --- 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 4e27d15f94a4fba8b2131a60f065bebc8868081b 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> Signed-off-by: Alexandra --- 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 21128cb2cab9495e43d94650b1abf892fd9959f1 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> Signed-off-by: Alexandra --- 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 5b9fd245733682ae72afbd4ad3efd54145afba3f 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> Signed-off-by: Alexandra --- 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 062de75676e18c02e2e111decbdb56610167e655 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> Signed-off-by: Alexandra --- 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 737be7439e7c042fd86b375d1636bf8b39e36451 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> Signed-off-by: Alexandra --- 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 7bb6e39434b86caf72b415d874c8c6c48dfa28d0 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> Signed-off-by: Alexandra --- 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 06b68ec2ab6c3baf2de14aba04182a908a426415 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> Signed-off-by: Alexandra --- 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 55a96d9baf6bf0d3104426f2b475f9dc00d7f55d 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> Signed-off-by: Alexandra --- 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 62bfe59b3a12df5c023a81cebe0414747e3ca136 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