To add a web server to your simulation, simply include the WebServer sim module into your S_define file:
+
+
#include "sim_objects/WebServer.sm"
+
+
Configuration of the Web Server
+
+
The following (input.py) parameters are available to configure your web server:
+
+
+
+
+
Parameter Name
+
Default Value
+
Description
+
+
+
+
+
+
web.server.enable
+
False
+
Must be explicitly enabled
+
+
+
web.server.port
+
"8888"
+
Web servers “listen” port
+
+
+
web.server.document_root
+
"www"
+
Web servers document root
+
+
+
web.server.debug
+
False
+
Print Client/Server Communication.
+
+
+
+
+
For your web server to be active, you must at least specify the following :
+
+
web.server.enable = True
+
+
+
To have your web server listen on port 8890, rather than 8888, you would specify:
+
+
web.server.port = "8890"
+
+
To serve files from a directory called my_document_root, rather than www:
+
+
web.server.document_root = "my_document_root"
+
+
To see client/server communication:
+
+
web.server.debug = True
+
+
When the Web Server Starts
+
+
The web server, if enabled, will start during sim initialization. When it does, it will look for the specified document root directory. By default that’s “www”. If root directory doesn’t exist, one will be created with a simple index.html file , a style sheet, and a couple of directories.
+
+
Connecting to Your Web Server
+
+
Assuming that you accepted the default port, connect to http://localhost:8888/ from your web browser. This will display the index.html file in your root directory.
+
+
The Default Document Root Directory
+
+
The default document root directory that was initially created for you is minimal.
+
+
www/
+ index.html
+ style.css
+ apps/
+ images/
+
+
index.html is the file that’s displayed when you connect to http://localhost:8888/.
+
+
style.css is a CSS style-sheet that’s included by index.html to give it some pizzazz.
+
+
The apps directory contains links to some example html/javascript applications
+ in $TRICK_HOME/trick_source/web/apps.
+
+
The images directory contains trick_icon.png.
+
+
You are encouraged to add to, modify, and/or delete these files and directories to best suite the needs of your project.
+
+
+
+
+
+
+
+
+
+
+
diff --git a/trick_source/web/docs/Adding_a_Web_Server_to_Your_Sim.md b/trick_source/web/docs/Adding_a_Web_Server_to_Your_Sim.md
new file mode 100644
index 00000000..3cb78ee6
--- /dev/null
+++ b/trick_source/web/docs/Adding_a_Web_Server_to_Your_Sim.md
@@ -0,0 +1,75 @@
+# Adding a Web Server to Your Sim
+
+To add a web server to your simulation, simply include the WebServer sim module into your **S_define** file:
+
+```
+#include "sim_objects/WebServer.sm"
+```
+
+## Configuration of the Web Server
+
+The following (input.py) parameters are available to configure your web server:
+
+|Parameter Name | Default Value| Description |
+|------------------------|--------------|----------------------------------|
+|web.server.enable | False |Must be explicitly enabled |
+|web.server.port | "8888" |Web servers “listen” port |
+|web.server.document_root| "www" |Web servers document root |
+|web.server.debug | False |Print Client/Server Communication.|
+
+For your web server to be active, you must at least specify the following :
+
+```python
+web.server.enable = True
+
+```
+
+To have your web server listen on port 8890, rather than 8888, you would specify:
+
+```python
+web.server.port = "8890"
+```
+
+To serve files from a directory called ```my_document_root```, rather than ```www```:
+
+```python
+web.server.document_root = "my_document_root"
+```
+
+To see client/server communication:
+
+```python
+web.server.debug = True
+```
+
+## When the Web Server Starts
+The web server, if enabled, will start during sim initialization. When it does, it will look for the specified document root directory. By default that’s “www”. If root directory doesn’t exist, one will be created with a simple index.html file , a style sheet, and a couple of directories.
+
+
+## Connecting to Your Web Server
+Assuming that you accepted the default port, connect to ```http://localhost:8888/``` from your web browser. This will display the index.html file in your root directory.
+
+
+## The Default Document Root Directory
+
+The default document root directory that was initially created for you is minimal.
+
+```
+www/
+ index.html
+ style.css
+ apps/
+ images/
+```
+
+**index.html** is the file that’s displayed when you connect to http://localhost:8888/.
+
+**style.css** is a CSS style-sheet that’s included by index.html to give it some pizzazz.
+
+The **apps** directory contains links to some example html/javascript applications
+ in ```$TRICK_HOME/trick_source/web/apps```.
+
+The **images** directory contains trick_icon.png.
+
+**You are encouraged to add to, modify, and/or delete these files and directories to best suite the needs of your project.**
+
diff --git a/trick_source/web/docs/Extending_the_HTTP-API.html b/trick_source/web/docs/Extending_the_HTTP-API.html
new file mode 100644
index 00000000..b2bd7d57
--- /dev/null
+++ b/trick_source/web/docs/Extending_the_HTTP-API.html
@@ -0,0 +1,583 @@
+
+
+
+
+
+
+
+Extending_the_HTTP-API
+
+
+
+
+
+
+
+
+
+
+
+
Extending the HTTP-API
+
+
The HTTP-API is implemented as a collection of httpMethodHandlers. An httpMethodHandler is a pointer to a function that is expected to respond to an HTTP GET request, using the Cesanta Mongoose framework. An httpMethodHandler is defined (in trick/WebServer.hh) as follows:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/trick_source/web/docs/Extending_the_HTTP-API.md b/trick_source/web/docs/Extending_the_HTTP-API.md
new file mode 100644
index 00000000..53cc69bd
--- /dev/null
+++ b/trick_source/web/docs/Extending_the_HTTP-API.md
@@ -0,0 +1,113 @@
+##Extending the HTTP-API
+
+The HTTP-API is implemented as a collection of ```httpMethodHandlers```. An ```httpMethodHandler``` is a pointer to a function that is expected to respond to an HTTP GET request, using the **Cesanta Mongoose** framework. An ```httpMethodHandler``` is defined (in ```trick/WebServer.hh```) as follows:
+
+
+
+
+
+```c
+typedef void (*httpMethodHandler)(struct mg_connection*, struct http_message*);
+```
+
+Documentation for the **Cesanta Mongoose Networking Library** can be found at:
+[https://cesanta.com/docs/overview/intro.html](https://cesanta.com/docs/overview/intro.html)
+
+## Example HTTP-API Extension
+
+Suppose you want your web server to send you a JSON message:
+
+```json
+{ "greeting" : "Hello Trick Sim Developer!" }
+```
+
+when you invoke the URL: ```http://localhost:8888/api/http/hello```.
+
+### Creating an ```httpMethodHandler```.
+
+The following two files will be our implementation of an ```httpMethodHandler```. We'll put these in some models directory ```httpMethods/```.
+
+**```handle_HTTP_GET_hello.h```**
+
+```c
+#ifndef HANDLE_HTTP_GET_HELLO
+#define HANDLE_HTTP_GET_HELLO
+
+#ifndef SWIG
+void handle_HTTP_GET_hello(struct mg_connection *nc, struct http_message *hm);
+#endif
+
+#endif
+```
+
+**```handle_HTTP_GET_hello.c```**
+
+```c
+#include "mongoose/mongoose.h"
+
+void handle_HTTP_GET_hello(struct mg_connection *nc, struct http_message *hm) {
+ mg_printf(nc, "%s", "HTTP/1.1 200 OK\r\nTransfer-Encoding: chunked\r\n\r\n");
+ const char* json_text =
+ "{ \"greeting\" : \"Hello Trick Sim Developer!\" }";
+ mg_printf_http_chunk(nc, "%s", json_text);
+ mg_send_http_chunk(nc, "", 0);
+}
+```
+
+### Installing our ```httpMethodHandler```.
+
+We'll do this from our **S_define** file:
+
+* Add ```(httpMethods/handle_HTTP_GET_hello.c)``` to the ```LIBRARY DEPENDENCIES```.
+
+* Include our header file:
+
+ ```##include "httpMethods/handle_HTTP_GET_hello.h"```
+
+* In ```create_connections()``` add :
+
+```c
+web.server.installHTTPGEThandler( "hello", &handle_HTTP_GET_hello );
+```
+### A Complete S_define
+
+```c++
+/***********************TRICK HEADER*************************
+PURPOSE:
+ (Cannon Numeric)
+LIBRARY DEPENDENCIES:
+ (
+ (cannon/gravity/src/cannon_init.c)
+ (cannon/gravity/src/cannon_numeric.c)
+ (httpMethods/handle_HTTP_GET_hello.c)
+ )
+*************************************************************/
+
+#include "sim_objects/default_trick_sys.sm"
+#include "sim_objects/WebServer.sm"
+##include "cannon/gravity/include/cannon_numeric.h"
+##include "httpMethods/handle_HTTP_GET_hello.h"
+
+class CannonSimObject : public Trick::SimObject {
+
+ public:
+ CANNON cannon ;
+ int foo;
+ CannonSimObject() {
+ ("default_data") cannon_default_data( &cannon ) ;
+ ("initialization") cannon_init( &cannon ) ;
+ ("derivative") cannon_deriv( &cannon ) ;
+ ("integration") trick_ret = cannon_integ( &cannon ) ;
+ ("dynamic_event") cannon_impact( &cannon) ;
+ }
+} ;
+CannonSimObject dyn ;
+
+IntegLoop dyn_integloop (0.01) dyn;
+
+void create_connections() {
+ dyn_integloop.getIntegrator(Runge_Kutta_4, 5);
+ web.server.installHTTPGEThandler( "hello", &handle_HTTP_GET_hello );
+}
+
+```
diff --git a/trick_source/web/docs/Extending_the_WS-API.html b/trick_source/web/docs/Extending_the_WS-API.html
new file mode 100644
index 00000000..c91b9ee9
--- /dev/null
+++ b/trick_source/web/docs/Extending_the_WS-API.html
@@ -0,0 +1,736 @@
+
+
+
+
+
+
+
+Extending_the_WS-API
+
+
+
+
+
+
+
+
+
+
+
+
Extending the WebSocket-API
+
+
When You Create a WebSocket Connection
+
+
Consider the following Javascript, that creates a web socket connection:
+
+
var ws = new WebSocket('ws://localhost:8888/api/ws/VariableServer');
+
+
In the URL: ws://localhost:8888/api/ws/VariableServer
+
+
+
ws:// specifies the protocol (web-socket in this case.)
+
localhost specifies the domain,
+
:8888 specifies the port, and
+
/api/ws/VariableServer specifies the path.
+
+
+
In the Trick web server, the path associated with a websocket must begin with
+/api/ws/. The remaining part of the path, i.e., VariableServer is the key that specifies the sub-protocol, prescribing what messages will be passed between client and server, and what those messages mean.
+
+
When a web-socket connection is established, the key will determine what type (sub-class) of WebSocketSession object to create, to manage the connection.
+
+
WebSocketSession
+
+
A WebSocketSession is a pure virtual base class meant to represent the state of one of potentially many websocket connections. It provides methods to:
+
+
+
Synchronously marshall Trick simulation data for out-going messages
+
Send messages to the websocket client, and
+
Receive and process messages from the websocket client.
+
+
+
To implement a new websocket sub-protocol, one needs to derive a new class from this base class, and implement the required methods. WebSocketSession.hh can be found in ${TRICK_HOME}/include/trick/.
Adding Your New WebSocketSession Type to the WebServer
+
+
To install your new websocket protocol, you'll need to create a function that
+creates an instance of your new WebSocketSession type. Then you'll need to call
+HTTP_Server::installWebSocketSessionMaker to install the function, with a
+label.
+
+
The function you'll create will take struct mg_connection * as an argument
+and return WebSocketSession*.
+
+
Example
+
+
Let's create a new web socket protocol that sends the time in GMT or local time.
+
+
First we'll derive a new type called TimeSession from WebSocketSession.
+
+
TimeSession.hh
+
+
/*************************************************************************
+PURPOSE: (Represent the state of a variable server websocket connection.)
+**************************************************************************/
+#ifndef TIMESESSION_HH
+#define TIMESESSION_HH
+#include <vector>
+#include <string>
+#include "time.h"
+#include "trick/WebSocketSession.hh"
+
+class TimeSession : public WebSocketSession {
+ public:
+ enum Zone { GMT, LOCAL};
+ TimeSession(struct mg_connection *nc);
+ ~TimeSession();
+ void marshallData();
+ void sendMessage();
+ int handleMessage(std::string);
+ private:
+ time_t now;
+ Zone zone;
+};
+
+WebSocketSession* makeTimeSession( struct mg_connection *nc );
+#endif
+
+
Below is our implementation. Notice the function makeTimeSession at the bottom.
We put TimeSession.cpp and TimeSession.cpp into a models directory called httpMethods/.
+
+
S_define Modifications
+
+
+
Specify the dependency on the httpMethods/TimeSession.cpp compilation unit.
+
We should already be including the WebServer sim object, otherwise we don't even have a webserver.
+
We need to include our new header file: ##include "httpMethods/TimeSession.hh"
+
Finally, install our WebSocketSession type: web.server.installWebSocketSessionMaker("Time", &makeTimeSession);
+The label we use for our protocol here is "Time", but it can be whatever name you choose.
To test your new web socket interface, put the following time.html file in $YOUR_SIM_DIRECTORY/www/apps. Then request http://localhost:8888/apps/time.html from your browser. You should see the time messages from your sim.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/trick_source/web/docs/Extending_the_WS-API.md b/trick_source/web/docs/Extending_the_WS-API.md
new file mode 100644
index 00000000..7faf00f5
--- /dev/null
+++ b/trick_source/web/docs/Extending_the_WS-API.md
@@ -0,0 +1,263 @@
+#Extending the WebSocket-API
+
+## When You Create a WebSocket Connection
+
+Consider the following Javascript, that creates a web socket connection:
+
+ ```var ws = new WebSocket('ws://localhost:8888/api/ws/VariableServer');```
+
+In the URL: ```ws://localhost:8888/api/ws/VariableServer```
+
+* ```ws://``` specifies the **protocol** (web-socket in this case.)
+* ```localhost``` specifies the **domain**,
+* ```:8888``` specifies the **port**, and
+* ```/api/ws/VariableServer``` specifies the **path**.
+
+In the Trick web server, the path associated with a websocket must begin with
+```/api/ws/```. The remaining part of the path, i.e., ```VariableServer``` is the **key** that specifies the **sub-protocol**, prescribing what messages will be passed between client and server, and what those messages mean.
+
+When a web-socket connection is established, the **key** will determine what type (sub-class) of ```WebSocketSession``` object to create, to manage the connection.
+
+## WebSocketSession
+A ```WebSocketSession``` is a pure virtual base class meant to represent the state of one of potentially many websocket connections. It provides methods to:
+
+ 1. Synchronously marshall Trick simulation data for out-going messages
+ 2. Send messages to the websocket client, and
+ 3. Receive and process messages from the websocket client.
+
+To implement a new websocket sub-protocol, one needs to derive a new class from this base class, and implement the required methods. ```WebSocketSession.hh``` can be found in ```${TRICK_HOME}/include/trick/```.
+
+### WebSocketSession.hh
+```c
+/*************************************************************************
+PURPOSE: (Represent Websocket connection.)
+**************************************************************************/
+#ifndef WEB_SOCKET_SESSION_HH
+#define WEB_SOCKET_SESSION_HH
+
+#include
+#ifndef SWIG
+#include "mongoose/mongoose.h"
+#endif
+
+class WebSocketSession {
+ public:
+ WebSocketSession(struct mg_connection *nc):connection(nc){};
+ virtual ~WebSocketSession() {};
+ virtual void marshallData()=0;
+ virtual void sendMessage()=0;
+ virtual int handleMessage(std::string)=0;
+
+ struct mg_connection* connection;
+};
+#endif
+```
+
+### Adding Your New WebSocketSession Type to the WebServer
+
+To install your new websocket protocol, you'll need to create a function that
+creates an instance of your new WebSocketSession type. Then you'll need to call
+```HTTP_Server::installWebSocketSessionMaker``` to install the function, with a
+label.
+
+The function you'll create will take ```struct mg_connection *``` as an argument
+and return ```WebSocketSession*```.
+
+## Example
+
+Let's create a new web socket protocol that sends the time in GMT or local time.
+
+First we'll derive a new type called ```TimeSession ``` from ```WebSocketSession```.
+
+### TimeSession.hh
+
+```c
+/*************************************************************************
+PURPOSE: (Represent the state of a variable server websocket connection.)
+**************************************************************************/
+#ifndef TIMESESSION_HH
+#define TIMESESSION_HH
+#include
+#include
+#include "time.h"
+#include "trick/WebSocketSession.hh"
+
+class TimeSession : public WebSocketSession {
+ public:
+ enum Zone { GMT, LOCAL};
+ TimeSession(struct mg_connection *nc);
+ ~TimeSession();
+ void marshallData();
+ void sendMessage();
+ int handleMessage(std::string);
+ private:
+ time_t now;
+ Zone zone;
+};
+
+WebSocketSession* makeTimeSession( struct mg_connection *nc );
+#endif
+```
+
+Below is our implementation. Notice the function ```makeTimeSession``` at the bottom.
+
+
+### TimeSession.cpp
+
+```c
+#include
+#include
+#include
+#include "TimeSession.hh"
+
+// CONSTRUCTOR
+TimeSession::TimeSession( struct mg_connection *nc ) : WebSocketSession(nc) {
+ time(&now);
+}
+
+// DESTRUCTOR
+TimeSession::~TimeSession() {}
+
+void TimeSession::marshallData() {
+ time(&now);
+}
+
+void TimeSession::sendMessage() {
+
+ char message[1024];
+ struct tm *theTime;
+ if (zone == TimeSession::LOCAL) {
+ theTime = localtime(&now);
+ } else {
+ theTime = gmtime(&now);
+ }
+ int hours = theTime->tm_hour;
+ int minutes = theTime->tm_min;
+ int seconds = theTime->tm_sec;
+ int day = theTime->tm_mday;
+ int month = theTime->tm_mon + 1;
+ int year = theTime->tm_year + 1900;
+
+ sprintf(message, "Time: %02d:%02d:%02d Date: %02d/%02d/%d\n", hours, minutes, seconds, month, day, year);
+ mg_send_websocket_frame(connection, WEBSOCKET_OP_TEXT, message, strlen(message));
+}
+
+int TimeSession::handleMessage(std::string client_msg) {
+
+ if (client_msg.compare("GMT") == 0) {
+ zone = TimeSession::GMT;
+ } else if (client_msg.compare("LOCAL") == 0) {
+ zone = TimeSession::LOCAL;
+ } else {
+ std::cerr << "ERROR: Unknown command \"" << client_msg << "\"." << std::endl;
+ }
+ return 0;
+}
+
+// WebSocketSessionMaker function for a TimeSession.
+WebSocketSession* makeTimeSession( struct mg_connection *nc ) {
+ std::cerr << "DEBUG: Creating new TimeSession." << std::endl;
+ return new TimeSession(nc);
+}
+```
+
+We put ```TimeSession.cpp``` and ```TimeSession.cpp``` into a models directory called ```httpMethods/```.
+
+
+### S_define Modifications
+
+1. Specify the dependency on the ```httpMethods/TimeSession.cpp``` compilation unit.
+2. We should already be including the WebServer sim object, otherwise we don't even have a webserver.
+3. We need to include our new header file: ```##include "httpMethods/TimeSession.hh"```
+4. Finally, install our WebSocketSession type: ```web.server.installWebSocketSessionMaker("Time", &makeTimeSession);```
+The label we use for our protocol here is "Time", but it can be whatever name you choose.
+
+```c++
+/***********************TRICK HEADER*************************
+PURPOSE:
+ (Cannon Numeric)
+LIBRARY DEPENDENCIES:
+ (
+ (cannon/gravity/src/cannon_init.c)
+ (cannon/gravity/src/cannon_numeric.c)
+ (httpMethods/TimeSession.cpp) // <--(1)
+ )
+*************************************************************/
+
+#include "sim_objects/default_trick_sys.sm"
+#include "sim_objects/WebServer.sm" // <--(2)
+##include "cannon/gravity/include/cannon_numeric.h"
+##include "httpMethods/TimeSession.hh" // <--(3)
+
+class CannonSimObject : public Trick::SimObject {
+
+ public:
+ CANNON cannon ;
+ int foo;
+ CannonSimObject() {
+ ("default_data") cannon_default_data( &cannon ) ;
+ ("initialization") cannon_init( &cannon ) ;
+ ("derivative") cannon_deriv( &cannon ) ;
+ ("integration") trick_ret = cannon_integ( &cannon ) ;
+ ("dynamic_event") cannon_impact( &cannon) ;
+ }
+} ;
+CannonSimObject dyn ;
+
+IntegLoop dyn_integloop (0.10) dyn;
+
+void create_connections() {
+ dyn_integloop.getIntegrator(Runge_Kutta_4, 5);
+ web.server.installWebSocketSessionMaker("Time", &makeTimeSession); // <--(4)
+}
+```
+
+
+## Testing The New WebSocket Interface
+
+To test your new web socket interface, put the following ```time.html``` file in ```$YOUR_SIM_DIRECTORY/www/apps```. Then request ```http://localhost:8888/apps/time.html``` from your browser. You should see the time messages from your sim.
+
+### time.html
+
+```html
+
+
+
+ WS Example
+
+
+
+
+
+
+```
+
+
+
+
diff --git a/trick_source/web/docs/HTTP-API_alloc_info.html b/trick_source/web/docs/HTTP-API_alloc_info.html
new file mode 100644
index 00000000..47f133fe
--- /dev/null
+++ b/trick_source/web/docs/HTTP-API_alloc_info.html
@@ -0,0 +1,633 @@
+
+
+
+
+
+
+
+HTTP-API_alloc_info
+
+
+
+
+
+
+
+
+
+
+
+
HTTP-API: alloc_info
+
+
http://localhost:8888/api/http/alloc_info
+
+
Purpose
+
+
Request a JSON encoded sub-list of allocation descriptors from the Memory Manager’s alloc_info list.
