Skip to content

Commit 987a3e2

Browse files
ccifraccifra
committed
Documentation updates
1 parent 4e46586 commit 987a3e2

File tree

4 files changed

+98
-85
lines changed

4 files changed

+98
-85
lines changed

‎README.md‎

Lines changed: 10 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ eexample/ExampleQueryServer.vi with query_server.proto defines a simple query se
77
You can either use the service as defined to implement a generic server via gPRC or use the implementation
88
as a pattern to implement a gRPC service of your design.
99

10-
the project supports Windows, Linux, and Linux RT.
10+
The project supports Windows, Linux, and Linux RT.
1111

1212
## Note: This project is not yet complete
1313
* Not all .proto data types are supported
@@ -17,100 +17,25 @@ the project supports Windows, Linux, and Linux RT.
1717

1818
## Creating a LabVIEW gRPC Server
1919

20-
1. (Windows Only) Download and install the latest [Microsoft Visual C++ Redistributable for Visual Studio 2015, 2017 and 2019](https://support.microsoft.com/en-us/topic/the-latest-supported-visual-c-downloads-2647da03-1eea-4433-9aff-95f26a218cc0).
21-
2. Navigate to the [Releases](https://github.com/ni/grpc-labview/releases) page.
22-
3. Download the latest Server Release `.zip` for the desired platform.
23-
4. Extract the contents of the `.zip` to a directory with read and write permissions.
20+
Step-by-step examples can be found in the [Creating a Server](docs/ServerCreation.md) guide
2421

25-
You can use the .proto scripting tool on Windows or Linux.
22+
### Examples
2623

27-
Open the project LabVIEW gRPC.lvproj from the LabVIEW gRPC folder in LabVIEW 2019 or later:
28-
29-
![LabVIEW gRPC.lvproj](docs/images/grpc-server-project.png "LabVIEW gRPC.lvproj")
30-
31-
Then open Main.vi from the project under Scripting Tools/gRPC Scripting Tools.lvlib:
32-
33-
![main.vi](docs/images/grpc-scripting-main.png "Main.vi")
34-
35-
* Select the .proto file you want to parse
36-
* Select the LabVIEW project you want the server VIs added to
37-
* Pick a name for the gRPC server
38-
* Run the VI to generate the server
39-
40-
You can generate multiple proto files and add them to the same LabVIEW project. You can also regenerate the same proto file into the same project with the same server name and the existing VIs will be updated to match the proto file. Code you add will not be touched.
41-
42-
Once the project is generated you can implement each of the server RPC methods. The generated project contains a LabVIEW class with a method for each RPC method:
43-
44-
![Generated Project](docs/images/generated-project.png "Generated Project")
45-
46-
### There are two ways to implement the server from the generated code.
47-
48-
* You can implement a `synchronous` server where all of the RPC methods are handled by a single event structure in 'Start Sync.vi`
49-
* You can implement an `asynchronus` server where each RPC method is handled by a corresponding LabVIEW Class method
50-
51-
### Async Server Implementation
52-
53-
Each method contains an event structure that registers for a event that is sent when the RPC call is received:
54-
55-
![RPC Implementation](docs/images/rpc-method.png "Method Implementation")
56-
57-
There are also several other events that are created
58-
* Server Stop - sent when the server is stopping. In response the VI should stop
59-
* Server Internal State - sent when the class state is updated by a call to `Set Server State.vi`
60-
* Invoke Internal - Helper event to enable communication between RPC methods
61-
62-
When the server is started an instance of each of the RPC Method member VIs is run asynchronously to handle parallel calls to different RPC methods.
63-
64-
In you method implementation to must use the Get RPC Method Get Input VI to get the RPC Request parameters and you must call the Set Output VI To set the RPC response of the method and to indicate that the RPC call has completed.
65-
66-
### Run the Server
67-
68-
* Open `Main.vi` from the project.
69-
* Select either `synchronous` or `asynchronous` with the `Enable Async` button
70-
* Fill in the Server Address which is in the form of `[address filter]:[port]`. Using `0.0.0.0:[port]` will allow connections from any computer
71-
* Fill in the path to certificate files if a TLS connection is required, see the section on SSL/TLS Support below for more imformation
72-
* Run the `Main.vi`
73-
74-
![RPC Server Main](docs/images/server-main.png "Server Main")
24+
Example servers are located in the examples foldes in the releases.
25+
* QueryServer - Example server which implements a Query / Invoke / Event API
26+
*
7527

28+
The examples include a python client that can be used to communicate with the example servers.
7629

7730
## Using the LabVIEW Client API
7831

7932
Coming Soon
8033

81-
## Example
82-
83-
There is an example server ExampleQueryServer.vi and a corresponding C++ client (example_client).
84-
When you build the C++ libraries the example client will also be built.
85-
8634
## SSL/TLS Support
8735

88-
You can enable SSL/TLS support on the server by passing in a path to a certificate and private key for the server.
89-
90-
You can generate the certificate with openssl using the following script.
91-
92-
```
93-
mypass="password123"
94-
95-
echo Generate server key:
96-
openssl genrsa -passout pass:$mypass -des3 -out server.key 4096
97-
98-
echo Generate server signing request:
99-
openssl req -passin pass:$mypass -new -key server.key -out server.csr -subj "/C=US/ST=TX/L=Austin/O=NI/OU=labview/CN=localhost"
100-
101-
echo Self-sign server certificate:
102-
openssl x509 -req -passin pass:$mypass -days 365 -in server.csr -signkey server.key -set_serial 01 -out server.crt
103-
104-
echo Remove passphrase from server key:
105-
openssl rsa -passin pass:$mypass -in server.key -out server.key
106-
107-
rm server.csr
108-
```
109-
110-
Clients then must connect using the server certificate that was generated (server.cer) otherwise the connection will fail.
111-
112-
If you do not passing in a certificate then the server will use insecure gRPC.
36+
The connection to the server can be secured using TLS (Server provided certificates) or Multual TLS (Client and Server provided certificates).
37+
See [Certificates](docs/Certificates.md) for more information.
11338

11439
## Building the server binaries
115-
To build the binaries for the scripting tool or the gRPC server see [Building](src/Building.md) for instructions.
40+
To build the binaries for the scripting tool or the gRPC server see [Building](docs/Building.md) for instructions.
11641

src/Building.md renamed to docs/Building.md

File renamed without changes.

‎docs/Certificates.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# SSL/TLS Support
2+
3+
You can enable SSL/TLS support on the server by passing in a path to a certificate and private key for the server.
4+
5+
You can generate the certificate with openssl using the following script.
6+
7+
```
8+
mypass="password123"
9+
10+
echo Generate server key:
11+
openssl genrsa -passout pass:$mypass -des3 -out server.key 4096
12+
13+
echo Generate server signing request:
14+
openssl req -passin pass:$mypass -new -key server.key -out server.csr -subj "/C=US/ST=TX/L=Austin/O=NI/OU=labview/CN=localhost"
15+
16+
echo Self-sign server certificate:
17+
openssl x509 -req -passin pass:$mypass -days 365 -in server.csr -signkey server.key -set_serial 01 -out server.crt
18+
19+
echo Remove passphrase from server key:
20+
openssl rsa -passin pass:$mypass -in server.key -out server.key
21+
22+
rm server.csr
23+
```
24+
25+
Clients then must connect using the server certificate that was generated (server.cer) otherwise the connection will fail.
26+
27+
If you do not passing in a certificate then the server will use insecure gRPC.

‎docs/ServerCreation.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# LabVIEW gRPC Server Creation
2+
3+
## Setup
4+
5+
1. (Windows Only) Download and install the latest [Microsoft Visual C++ Redistributable for Visual Studio 2015, 2017 and 2019](https://support.microsoft.com/en-us/topic/the-latest-supported-visual-c-downloads-2647da03-1eea-4433-9aff-95f26a218cc0).
6+
2. Navigate to the [Releases](https://github.com/ni/grpc-labview/releases) page.
7+
3. Download the latest Server Release `.zip` for the desired platform.
8+
4. Extract the contents of the `.zip` to a directory with read and write permissions.
9+
10+
## Server Creation
11+
12+
You can use the .proto scripting tool on Windows or Linux.
13+
14+
Open the project LabVIEW gRPC.lvproj from the LabVIEW gRPC folder in LabVIEW 2019 or later:
15+
16+
![LabVIEW gRPC.lvproj](images/grpc-server-project.png "LabVIEW gRPC.lvproj")
17+
18+
Then open Main.vi from the project under Scripting Tools/gRPC Scripting Tools.lvlib:
19+
20+
![main.vi](images/grpc-scripting-main.png "Main.vi")
21+
22+
* Select the .proto file you want to parse
23+
* Select the LabVIEW project you want the server VIs added to
24+
* Pick a name for the gRPC server
25+
* Run the VI to generate the server
26+
27+
You can generate multiple proto files and add them to the same LabVIEW project. You can also regenerate the same proto file into the same project with the same server name and the existing VIs will be updated to match the proto file. Code you add will not be touched.
28+
29+
Once the project is generated you can implement each of the server RPC methods. The generated project contains a LabVIEW class with a method for each RPC method:
30+
31+
![Generated Project](images/generated-project.png "Generated Project")
32+
33+
### There are two ways to implement the server from the generated code.
34+
35+
* You can implement a `synchronous` server where all of the RPC methods are handled by a single event structure in 'Start Sync.vi`
36+
* You can implement an `asynchronus` server where each RPC method is handled by a corresponding LabVIEW Class method
37+
38+
### Async Server Implementation
39+
40+
Each method contains an event structure that registers for a event that is sent when the RPC call is received:
41+
42+
![RPC Implementation](images/rpc-method.png "Method Implementation")
43+
44+
There are also several other events that are created
45+
* Server Stop - sent when the server is stopping. In response the VI should stop
46+
* Server Internal State - sent when the class state is updated by a call to `Set Server State.vi`
47+
* Invoke Internal - Helper event to enable communication between RPC methods
48+
49+
When the server is started an instance of each of the RPC Method member VIs is run asynchronously to handle parallel calls to different RPC methods.
50+
51+
In you method implementation to must use the Get RPC Method Get Input VI to get the RPC Request parameters and you must call the Set Output VI To set the RPC response of the method and to indicate that the RPC call has completed.
52+
53+
### Run the Server
54+
55+
* Open `Main.vi` from the project.
56+
* Select either `synchronous` or `asynchronous` with the `Enable Async` button
57+
* Fill in the Server Address which is in the form of `[address filter]:[port]`. Using `0.0.0.0:[port]` will allow connections from any computer
58+
* Fill in the path to certificate files if a TLS connection is required, see the section on SSL/TLS Support below for more imformation
59+
* Run the `Main.vi`
60+
61+
![RPC Server Main](docs/images/server-main.png "Server Main")

0 commit comments

Comments
 (0)