From 93ea9d705bf4025469e369d48b6f5de416386605 Mon Sep 17 00:00:00 2001
From: Jaremy Creechley <creechley@gmail.com>
Date: Sun, 29 Nov 2020 16:47:59 -0700
Subject: [PATCH] updating readme

---
 esp-idf-examples/simplewifi-rpc/.gitignore |  1 +
 esp-idf-examples/simplewifi-rpc/Makefile   |  8 ++++----
 esp-idf-examples/simplewifi-rpc/README.md  | 18 ++++++++++++++++++
 3 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/esp-idf-examples/simplewifi-rpc/.gitignore b/esp-idf-examples/simplewifi-rpc/.gitignore
index b76e2b7..b6f24cd 100644
--- a/esp-idf-examples/simplewifi-rpc/.gitignore
+++ b/esp-idf-examples/simplewifi-rpc/.gitignore
@@ -5,3 +5,4 @@ src/localnim/
 .env
 results.json
 main/nimble/
+rpc_cli
diff --git a/esp-idf-examples/simplewifi-rpc/Makefile b/esp-idf-examples/simplewifi-rpc/Makefile
index 22746f0..aa0c2a4 100644
--- a/esp-idf-examples/simplewifi-rpc/Makefile
+++ b/esp-idf-examples/simplewifi-rpc/Makefile
@@ -16,19 +16,19 @@ default: mpack_rpc_queue_server
 
 json_rpc_server: clean
 	nim prepare main/wifi_example_main.nim --nimblePath:$(NIMBLE)/pkgs -d:$(ESP_IDF_VERSION) -d:TcpMpackRpcServer $(NIMFLAGS) && idf.py reconfigure 
-	nim c --nimblePath:$(NIMBLE)/pkgs -d:TcpMpackRpcServer rpc_cli_test.nim
+	nim c --nimblePath:$(NIMBLE)/pkgs -d:TcpMpackRpcServer -o:rpc_cli rpc_cli_test.nim 
 
 mpack_rpc_server: clean
 	nim prepare main/wifi_example_main.nim --nimblePath:$(NIMBLE)/pkgs -d:$(ESP_IDF_VERSION) -d:TcpMpackRpcServer $(NIMFLAGS) && idf.py reconfigure 
-	nim c --nimblePath:$(NIMBLE)/pkgs -d:TcpMpackRpcServer  rpc_cli_test.nim
+	nim c --nimblePath:$(NIMBLE)/pkgs -d:TcpMpackRpcServer -o:rpc_cli rpc_cli_test.nim 
 
 mpack_rpc_queue_server: clean
 	nim prepare main/wifi_example_main.nim --nimblePath:$(NIMBLE)/pkgs -d:$(ESP_IDF_VERSION) -d:TcpMpackRpcQueueServer $(NIMFLAGS) && idf.py reconfigure 
-	nim c --nimblePath:$(NIMBLE)/pkgs -d:TcpMpackRpcQueueServer  rpc_cli_test.nim
+	nim c --nimblePath:$(NIMBLE)/pkgs -d:TcpMpackRpcQueueServer -o:rpc_cli rpc_cli_test.nim 
 
 tcp_echo_server: clean
 	nim prepare main/wifi_example_main.nim --nimblePath:$(NIMBLE)/pkgs -d:$(ESP_IDF_VERSION) -d:TcpEchoServer $(NIMFLAGS) && idf.py reconfigure 
-	nim c --nimblePath:$(NIMBLE)/pkgs -d:TcpEchoServer rpc_cli_test.nim
+	nim c --nimblePath:$(NIMBLE)/pkgs -d:TcpEchoServer -o:rpc_clirpc_cli_test.nim 
 
 build: 
 	idf.py build
diff --git a/esp-idf-examples/simplewifi-rpc/README.md b/esp-idf-examples/simplewifi-rpc/README.md
index 12b69f7..2ee165c 100644
--- a/esp-idf-examples/simplewifi-rpc/README.md
+++ b/esp-idf-examples/simplewifi-rpc/README.md
@@ -41,3 +41,21 @@ idf.py -p [port] monitor
 # or together:
 idf.py -p [port] flash monitor
 ```
+
+## Testing Example 
+
+The RPC methods use raw sockets and `selectors` library from Nim's stdlib. This allows the ESP32 code to efficiently check sockets for new messages. The makefile now builds a variant of `rpc_cli` that should work with the chosen method (e.g. mpack or json).
+
+Run it like: 
+
+```sh
+./rpc_cli --ip:$IP --count:1 '{"method": "add", "params": [1,2]}' 
+```
+
+## Notes on the RPC protocol
+
+The `rpc_cli` should give an example of the RPC protocol used. It's roughly based on JSON-RPC, however, using raw socket require a bit more work. Sending RPC messages are sent "raw", e.g. just the message. This limits RPC calls to 1400 bytes and could be fixed in the future. 
+
+For receiving the RPC responses, a very simple protocol is used based on the Erlang "ports" protocol. A 4-byte signed integer with the size of the RPC result is sent first, in network byte order. The RPC client must read these 4 bytes, then read the number of bytes sent. The `rpc_cli` provides an example of how to do this in Nim. This enables returning message that are larger than 1400 bytes. Ideally, this will be done for the incoming RPC message as well. 
+
+The JSON version of the rpc server currently returns a "raw" response.