RIC-1139: New sample TrafficLightWeb

Author: mattias-mohlin

art-samples/TrafficLightWeb/PedLight.art

@@ -0,0 +1,32 @@
+// Represents the pedestrian light that can show either
+// the Stop or Go symbols.
+capsule PedLight {
+    service behavior port pedControl : PedLightControl;
+    service behavior notify port server~ : PedLightControl;
+
+    statemachine {
+        state DoNotWalk {
+            entry
+            `
+                server.stop().send();
+            `;
+        };
+        state Walk {
+            entry
+            `
+                server.walk().send();
+            `;
+
+            countdown: on pedControl.timeRemaining
+            `
+                int time = * static_cast<const int*>(rtdata);
+                server.timeRemaining(time).send();
+            `;
+        };
+        state WaitForUIReady;
+        initial -> WaitForUIReady;
+        WaitForUIReady -> DoNotWalk on server.rtBound;
+        walk: DoNotWalk -> Walk on pedControl.walk;        
+        stop: Walk -> DoNotWalk on pedControl.stop;
+    };
+};

art-samples/TrafficLightWeb/PedLightControl.art

@@ -0,0 +1,10 @@
+// This protocol is used both for internal communication between the
+// traffic light and the pedestrian light, but also for the communication
+// between the pedestrian light and the web server.
+protocol PedLightControl {    
+    in stop();
+    in walk();   
+
+    // Notify about how many seconds remain until the light goes from Walk to Stop
+    in timeRemaining(`int`); 
+};

art-samples/TrafficLightWeb/README.md

@@ -0,0 +1,32 @@
+# traffic-light-web
+<img src="webapp/public/images/screenshot.png" width="100" height="100">
+
+This sample implements a traffic light system consisting of two lights (one for traffic and one for pedestrians) and a push button (for pedestrians to push when they want to safely cross the street). The realtime application uses the [TCPServer library](../TcpServer/README.md) in order to communicate with a Node.js web application. Information about current states of the lights are updated on the web page in real time, and pushing the button on the web page will inject the request from the pedestrian to cross the street. 
+
+To be able to intercept the outgoing messages about light changes, the Node.js application embeds a simple TCP server. Hence, this sample implements bi-directional communication using two separate TCP servers (one in the Node.js application and one in the realtime C++ application).
+
+## Starting the web server
+`cd webapp`
+
+`npm install`
+
+`node app.js`
+
+Open [http://localhost:4000/](http://localhost:4000/) in a web browser
+
+## Launch the realtime application
+`TLSystem.exe -URTS_DEBUG=quit -port=<P> -remotePort=<RP> -remoteHost="<RH>"` 
+
+All arguments are optional and have default values:
+* port: 9911 (TCP port used by realtime app)
+* remotePort: 2234 (TCP port used by web app)
+* remoteHost: `127.0.0.1` (IP address or hostname where the web app runs)
+
+## How the application works
+When the application starts the top capsule `TLSystem` incarnates the optional `server` part with a `WebServer` capsule instance. This capsule inherits from the `TCPServer` capsule which is responsible for the communication with the Node.js application. The `WebServer` runs in its own thread to avoid that the TCP communication affects the performance of the rest of the application. 
+
+The other capsules `TrafficLight` and `PedLight` represent the two lights and have state machines that implement the switching of the lights based on timers. The `TrafficLight` controls the `PedLight` so that pedestrians can safely cross the street when they request to do so. Note that both light capsule state machines have to wait initially for the `WebServer` to become available, and they do this by means of notification ports.
+
+The Node.js application makes a "pedestrian" request when the button is pushed on the web page. From the realtime application's point of view this becomes an incoming TCP request which is mapped to the injection of the `pedestrian` event on the `trafficLight` port of `WebServer`. In the other direction, outgoing events about light changes become TCP requests which the TCP server in the Node.js application will handle. It then uses web sockets for updating the web time accordingly.
+
+The application also supports a `pedestrianCustomTime` event which has a parameter the specifies how many seconds the pedestrians will get for crossing the street. There is no user interface on the web page for sending this event, but you can use the Art Debugger for injecting it. This emulates a situation where a new feature has been implemented in a realtime application for which no user interface (or hardware) is yet available.

art-samples/TrafficLightWeb/TLSystem.art

@@ -0,0 +1,65 @@
+// Top capsule representing a traffic light system that consists of a 3-color light
+// and a pedestrian button. The traffic light circles red->green->yellow->red->... until
+// the pedestrian button is pressed. Then the traffic light turns red for some time
+// so the pedestrian can cross the street. After that it resumes circling through the colors.
+// A user interface, implemented as a Node.js web application, shows the current color of the traffic light and provides
+// the pedestrian button to push.
+
+capsule TLSystem {
+    [[rt::header_preface]]
+    `
+        #include <string>
+    `
+    [[rt::decl]]
+    `
+        private: 
+            unsigned int port = 0; // TCP server port of realtime app
+            unsigned int remotePort = 0; // TCP server port of Node.js app
+            std::string remoteHost = ""; // TCP server host of Node.js app
+            void parseCommandLine();
+    `
+
+    [[rt::impl]]
+    `
+        void TLSystem::parseCommandLine() {
+            int ac = RTMain::argCount();
+            const char * const * av = RTMain::argStrings();
+            std::string arg_remotePort = "-remotePort=", arg_remoteHost = "-remoteHost=", arg_port = "-port=";
+        
+            while( --ac > 0 ) {
+                std::string arg = *++av; 
+                if (arg.compare(0, arg_remotePort.size(), arg_remotePort) == 0 )
+                    remotePort = RTMemoryUtil::atoi(*av + arg_remotePort.size());
+                else if (arg.compare(0, arg_remoteHost.size(), arg_remoteHost) == 0 ) {
+                    remoteHost = arg.substr(arg_remoteHost.size());
+                }
+                else if (arg.compare(0, arg_port.size(), arg_port) == 0 )
+                    port = RTMemoryUtil::atoi(*av + arg_port.size());
+            }            
+        }
+    `
+    
+    behavior port frame : Frame;
+
+    part trafficLight : TrafficLight;
+    optional part server [[rt::properties(rule_config="X0039")]] : WebServer; // Intentionally unconnected    
+    part pedLight : PedLight;
+
+    connect server.trafficLight with trafficLight.server;
+    connect pedLight.pedControl with trafficLight.pedLightControl;
+    connect pedLight.server with server.pedLightControl;
+ 
+    statemachine {
+        state State;
+        initial -> State
+        `
+            parseCommandLine();
+
+            RTActorId id = frame.incarnateCustom(server, 
+                RTActorFactory([this](RTController * c, RTActorRef * a, int index) {
+                    return new WebServer(ServerThread, a, port, remotePort, remoteHost);
+                }
+            ));
+        `;
+    };
+};

art-samples/TrafficLightWeb/TrafficLight.art

@@ -0,0 +1,150 @@
+// A traffic light that can show either red, green or yellow. It can accept a pedestrian request
+// and will then control a pedestrian light so the pedestrian can safely cross the street.
+capsule TrafficLight {
+[[rt::decl]]
+`
+    private: 
+        RTTimerId cycleTimer; 
+        int pedestrianWalkTime;
+`
+
+    behavior port log : Log;    
+    behavior port timer : Timing;
+    behavior port pedTimer : Timing;
+    
+    service behavior notify port server : TrafficLightControl;
+    service behavior port pedLightControl~ : PedLightControl;
+
+    statemachine {
+        state WaitUntilServerReady;
+        state CycleLight {
+            entrypoint ep, pedReady;
+            exitpoint pedRequest;
+
+            state Red[[rt::properties(color="#e60f0f")]] {
+                entry 
+                `
+                    server.red().send();
+                `;
+            }, 
+            Green[[rt::properties(color="#11d80e")]] {
+                entry 
+                `
+                    server.green().send();
+                `;
+            }, 
+            Yellow[[rt::properties(color="#edc707")]] {
+                entry 
+                `                    
+                    server.yellow().send();
+                `;
+            };
+
+            ep -> Red;
+            red_to_green: Red -> Green on timer.timeout
+            `
+                log.log("Red -> Green");
+                log.commit();
+            `
+            ;
+            green_to_yellow: Green -> Yellow on timer.timeout
+            `
+                log.log("Green -> Yellow");
+                log.commit();
+            `
+            ;
+            yellow_to_red: Yellow -> Red on timer.timeout
+            `
+                log.log("Yellow -> Red");
+                log.commit();
+            `
+            ;
+
+            pedReady -> Red;
+        };
+        initial -> WaitUntilServerReady;
+    
+        WaitUntilServerReady -> CycleLight.ep on server.rtBound
+        `
+            log.log("TrafficLight starts up");
+            log.commit();
+            cycleTimer = timer.informEvery(RTTimespec(2,0));
+        `;
+
+        state PedestrianCrossing {
+            entrypoint pedRequest;
+            exitpoint pedReady;
+
+            entry
+            `
+                int pedTimerData = -1; 
+                pedTimer.informIn(RTTimespec(2,0), &pedTimerData, &RTType_int);
+            `;
+
+            state Red [[rt::properties(color="#e60f0f")]] {
+                entry
+                `
+                    log.log("Enter Red");
+                    log.commit();
+                    server.red().send();
+                `;
+            };
+
+            pedRequest -> Red;
+
+            updatePedLight: on pedTimer.timeout
+            `
+                int pedTimerData = * static_cast<const int*>(rtdata);
+
+                if (pedTimerData == -1) {
+                    pedLightControl.walk().send();
+                    pedTimerData = pedestrianWalkTime; // Count down number of seconds until we switch from Walk to Stop
+                    pedLightControl.timeRemaining(pedTimerData).send();
+                    pedTimer.informIn(RTTimespec(1,0), &pedTimerData, &RTType_int);
+                    // Time for pedestrians to cross
+                }                
+                else if (pedTimerData == 0) {
+                    pedLightControl.stop().send();
+                    timer.informIn(RTTimespec(2,0));
+                }
+                else {
+                    pedTimerData--;
+                    pedLightControl.timeRemaining(pedTimerData).send();                    
+                    pedTimer.informIn(RTTimespec(1,0), &pedTimerData, &RTType_int);
+                }
+            `;
+
+            pedRequest_ignored: on server.pedestrian, server.pedestrianCustomTime
+            `
+                // Ignore additional requests from pedestrians since we already are in the PedestriansCrossing state.
+            `;
+        };
+
+        junction j;
+
+        pedRequest : CycleLight.pedRequest -> j on server.pedestrian
+        `
+            // Use a default walk time for the pedestrian of 4 seconds
+            pedestrianWalkTime = 4;
+        `;
+
+        pedRequestCustom : CycleLight.pedRequest -> j on server.pedestrianCustomTime
+        `
+            pedestrianWalkTime = * static_cast<const int*>(rtdata);
+        `;
+
+        j -> PedestrianCrossing.pedRequest
+        `
+            log.log("Pedestrian requests to cross");
+            log.commit();
+            timer.cancelTimer(cycleTimer);
+        `;
+
+        pedReady: PedestrianCrossing.pedReady -> CycleLight.pedReady on timer.timeout
+        `
+            log.log("Pedestrians ready");
+            log.commit();
+            cycleTimer = timer.informEvery(RTTimespec(2,0));
+        `;
+    };
+};

art-samples/TrafficLightWeb/TrafficLightControl.art

@@ -0,0 +1,10 @@
+protocol TrafficLightControl {
+    // Events to notify that the traffic light color has changed
+    out green();
+    out red();
+    out yellow();
+
+    in pedestrian(); // Sent when a pedestrian pushes the button
+    
+    in pedestrianCustomTime(`int`); // Request pedestrian crossing with custom time
+};

art-samples/TrafficLightWeb/WebServer.art

@@ -0,0 +1,41 @@
+// Interface to the web server
+capsule WebServer : TCPServer {
+    [[rt::header_preface]]
+    `
+        #include <string>
+    `
+    [[rt::impl_preface]]
+    `
+        #include <iostream>
+    `
+    [[rt::decl]]
+    `
+    public:
+        WebServer(RTController* rtg_rts, RTActorRef* rtg_ref, unsigned int port, unsigned int remotePort, std::string& remoteHost);
+    `
+
+    [[rt::impl]]
+    `
+        WebServer::WebServer(RTController* rtg_rts, RTActorRef* rtg_ref, unsigned int port, unsigned int remotePort, std::string& remoteHost)
+            : SUPER(rtg_rts, rtg_ref) {
+            if (port != 0)
+                config.port = port; 
+            if (remotePort != 0)
+                config.remotePort = remotePort;
+            if (!remoteHost.empty()) {
+                config.remoteHost = remoteHost;                
+            }
+            
+            config.logToStdOut = false;       
+            std::cout << "Server started!" << std::endl;
+            std::cout << "port=" << config.port << " remotePort=" << config.remotePort << " remoteHost=" << config.remoteHost << "!" << std::endl;
+        }
+    `
+
+    service behavior port trafficLight~ : TrafficLightControl;
+    service behavior port pedLightControl: PedLightControl;
+ 
+    statemachine {
+        
+    };
+};

art-samples/TrafficLightWeb/app.tcjs

@@ -0,0 +1,30 @@
+//Transformation Configuration File
+let tc = TCF.define(TCF.ART_TO_CPP);
+tc.targetFolder = 'TrafficLightWeb_target'; 
+tc.prerequisites = ['../TcpServer/tcpServerLib.tcjs'];
+
+// Uncomment to debug
+/*
+tc.compileArguments = '$(DEBUG_TAG)';
+tc.linkArguments = '/DEBUG';
+tc.targetConfiguration = "WinT.x64-VisualC++-17.0";
+tc.targetRTSLocation = "C:/git/rsarte-target-rts/rsa_rt/C++/TargetRTS";
+*/
+tc.topCapsule = "TLSystem";
+tc.threads = [
+    {
+        name: 'MainThread',
+        implClass: 'RTPeerController',
+        stackSize: '20000',
+        priority: 'DEFAULT_MAIN_PRIORITY'        
+    },
+    {
+        name: 'ServerThread',
+        implClass: 'RTPeerController',
+        stackSize: '20000',
+        priority: 'DEFAULT_MAIN_PRIORITY',
+        logical: [
+            'ServerThread'
+        ]
+    }
+];