This project builds out both host tools running on the host side, and an application running on the device side. The device application consists of iwasm, application library, application manager, timers and sensors support. The device runs on Linux OS and interacts with host tools.
It demonstrates an end to end scenario, the wasm applications life cycle management and communication programming models.
Directory structure
------------------------------
```
simple/
├── build.sh
├── CMakeLists.txt
├── README.md
├── src
│ ├── ext_lib_export.c
│ ├── iwasm_main.c
│ └── main.c
└── wasm-apps
├── event_publisher
│ └── event_publisher.c
├── event_subscriber
│ └── event_subscriber.c
├── request_handler
│ └── request_handler.c
├── request_sender
│ └── request_sender.c
├── sensor
│ └── sensor.c
└── timer
└── timer.c
```
- build.sh<br/>
The script to build all binaries.
- CMakeLists.txt<br/>
CMake file used to build the simple application.
- README.md<br/>
The file you are reading currently.
- src/ext_lib_export.c<br/>
This file is used to export native APIs. See the `The mechanism of exporting Native API to WASM application` section in WAMR README.md for detail.
- src/iwam_main.c<br/>
This file is the implementation by platform integrator. It implements the interfaces that enable the application manager communicating with the host side. See `{WAMR_ROOT}/core/app-mgr/app-mgr-shared/app_manager_export.h` for the definition of the host interface.
```
/* Interfaces of host communication */
typedef struct host_interface {
host_init_func init;
host_send_fun send;
host_destroy_fun destroy;
} host_interface;
```
```
host_interface interface = {
.init = host_init,
.send = host_send,
.destroy = host_destroy
};
```
This interface is passed to application manager by calling
```
app_manager_startup(&interface);
```
The `host_init_func` is called when the application manager starts up. And `host_send_fun` is called by the application manager to send data to the host.
>**Note:** Currently application manager keeps running and never exit, `host_destroy_fun` has no chance to get executed. So you can leave this API implementation empty.
- src/main.c<br/>
The main file.
- wasm-apps<br/>
Source files of sample wasm applications.
Build all binaries
==============
Execute the build.sh script then all binaries including wasm application files would be generated in 'out' directory.
`./build.sh`
Out directory structure
------------------------------
```
out/
├── host_tool
├── simple
└── wasm-apps
├── event_publisher.wasm
├── event_subscriber.wasm
├── request_handler.wasm
├── request_sender.wasm
├── sensor.wasm
└── timer.wasm
```
- host_tool:
A small testing tool to interact with WAMR. See the usage of this tool by executing "./host_tool -h".
`./host_tool -h`
- simple:
A simple testing tool running on the host side that interact with WAMR. It is used to install, uninstall and query WASM applications in WAMR, and send request or subscribe event, etc. See the usage of this application by executing "./simple -h".
`./simple -h`
>****Note:**** The connection between simple and host_tool is TCP by default and is what this guide uses. The simple application works as a server and the host_tool works as a client. You can also use UART connection. To achieve this you have to uncomment the below line in CMakeLists.txt and rebuild. You have to set up a UART hardware connection between 2 machines one of which runs the host_tool and the other runs the simple application. See the help of host_tool and the simple application to know how to specify UART device parameters.<br/>
`#add_definitions (-DCONNECTION_UART)`
- wasm-apps:
Sample wasm applications that demonstrate all APIs of the WAMR programming model. The source codes are in the wasm-apps directory under the root of this project.
+ event_publisher.wasm<br/>
This application shows the sub/pub programming model. The pub application publishes the event "alert/overheat" by calling api_publish_event() API. The subscriber could be host_tool or other wasm application.
+ event_subscriber.wasm<br/>
This application shows the sub/pub programming model. The sub application subscribes the "alert/overheat" event by calling api_subscribe_event() API so that it is able to receive the event once generated and published by the pub application. To make the process clear to interpret, the sub application dumps the event when receiving it.
+ request_handler.wasm<br/>
This application shows the request/response programming model. The request handler application registers 2 resources(/url1 and /url2) by calling api_register_resource_handler() API. The request sender could be host_tool or other wasm application.
+ request_sender.wasm<br/>
This application shows the request/response programming model. The sender application sends 2 requests, one is "/app/request_handler/url1" and the other is "url1". The former is an accurate request which explicitly specifies the name of request handler application in the middle of the URL and the later is a general request.
+ sensor.wasm<br/>
This application shows the sensor programming model. It opens a test sensor and configures the sensor event generating interval to 1 second. To make the process clear to interpret, the application dumps the sensor event when receiving it.
+ timer.wasm<br/>
This application shows the timer programming model. It creates a periodic timer that prints the current expiry number in every second.
Run the scenario
==========================
- Enter the out directory<br/>
```
$ cd ./out/
```
- Startup the 'simple' process works in TCP server mode and you would see "App Manager started." is printed.<br/>
```
$ ./simple -s
App Manager started.
```
- Query all installed applications<br/>
```
$ ./host_tool -q
response status 69
{
"num": 0
}
```
The `69` stands for response status to this query request which means query success and a payload is attached with the response. See `{WAMR_ROOT}/core/iwasm/lib/app-libs/base/wasm_app.h` for the definitions of response codes. The payload is printed with JSON format where the `num` stands for application installations number and value `0` means currently no application is installed yet.
- Install the request handler wasm application<br/>
The `65` stands for response status to this installation request which means success.
Output of simple
```
Install WASM app success!
sent 16 bytes to host
WASM app 'request_handler' started
```
Now the request handler application is running and waiting for host or other wasm application to send a request.
- Query again<br/>
```
$ ./host_tool -q
response status 69
{
"num": 1,
"applet1": "request_handler",
"heap1": 49152
}
```
In the payload, we can see `num` is 1 which means 1 application is installed. `applet1`stands for the name of the 1st application. `heap1` stands for the heap size of the 1st application.
- Send request from host to specific wasm application<br/>
```
$ ./host_tool -r /app/request_handler/url1 -A GET
response status 69
{
"key1": "value1",
"key2": "value2"
}
```
We can see a response with status `69` and a payload is received.
