WCPS: Wireless Cyber-Physical Simulator

End-user's Tutorial on using WCPS: Wireless Cyber-Physical Simulator

Normal User Tutorial on the Wireless Cyber-Physical Simulator(WCPS) WCPS is design for, but not limited to, realistic Wireless Structural Control simulations. The layered infrastructure and efficient integration of state-of-the-art control and wireless networking tools, i.e., Simulink and TOSSIM, have made WCPS an ideal choice for general wireless control simulations with Simulink and TOSSIM.

As an exemplary example of Cyber-Physical Systems that perform close-loop control using real-time sensor data collected through wireless sensor networks, Wireless Structural Control (WSC) systems can play a crucial role in protecting civil infrastructure in the events of earth quakes and other natural disasters. Existing WSC research usually employ wireless sensors installed on small lab structures, which cannot capture realistic delays and data loss in wireless sensor networks deployed on large civil structures and their impacts on structural control. The lack of realistic studies and tools that capture both the cyber (wireless) and physical (structures) aspects of WSC systems represent a hurdle for cyber-physical systems research for civil infrastructure.

WCPS advances the state of the art of WSC and Cyber-physical System through the following contributions. First, it for the first time presents an integrated environment that combines realistic simulations of both wireless sensor networks and structures. WCPS integrates Simulink and TOSSIM, a state-of-the-art sensor network simulator featuring a realistic wireless model seeded by signal traces. Second, release of WCPS in comprised of two realistic case studies each matching a structural model with wireless traces collected from real-world environments. The building study combines a benchmark building model and wireless traces collected from a multi-story building. The bridge study combines the structural model of the Cape Girardeau bridge over the Mississippi River and wireless traces collected from a similar bridge (the Jindo Bridge) in Korea. These case studies shed lights on the challenges of WSC and the limitations of a traditional structural controller under realistic wireless conditions.

The following tutorial introduces in detail how to configure general MATLAB, TinyOS, and PYTHON environments, as well as the WCPS framework. The tutorial herein is an end-user version specifically for end-users that do not do much development but instead trying to do wireless control simulations with Simulink, TOSSIM and WCPS. An advanced tutorial on in-depth TinyOS development (e.g., routing protoocls, MAC layer development) with WCPS can be found [here].

Software Environment Setup

Software Requirements

Install TinyOS

WCPS is implemented and tested on MacOS X (snowleopard), Windows XP, and Windows 7. Current release of WCPS is under TinyOS 2.1.1, which can be installed following the three methods.

• 1. Follow the TinyOS official tutorial on installation of TinyOS for your specific platform: Link
• 2. Directly download the pre-tested TinyOS 2.1.1 image from here: [under construction Cygwin] [under construction Mac OS X]

Install Mac Layer Architecture(MLA)

• Follow the instructions here: Install MLA.

Install MATLAB and Simulink

If you already have MATLAB MATLAB 7.11.0.584 (2010b) or later version, skip this step. Otherwise, follow the tutorial here: install MATLAB

Install Python

If you already have Python 2.7.2 or later version installed, skip this step. Otherwise, follow the manual here: install Python

Building a Wireless Network in TOSSIM

• 1. Makefile

"Makefile" takes advantage of the fact that it's not necessary to recompile all the project files that has not been changed. To have the "Makefile" for our project, copy the code below into a txt file and save as "Makefile" without any suffix, or simply download it here: [Makefile]

# target file
COMPONENT=TestNetworkAppC
# dependencies of the target
include $(UPMA_DIR)/Makefile.include
BUILD_EXTRA_DEPS = TestNetworkMsg.py
CFLAGS += -DTOSH_DATA_LENGTH=156
CFLAGS += -I$(TOSDIR)/lib/T2Hack
PFLAGS += -I../../../pure-tdma
CFLAGS += -I$(TOSDIR)/lib/printf
CFLAGS += -DFOOTER_SIZE=0 -DTDMA -DUPMA
#TDMA mac layer
UPMA_MAC = pure-tdma
#mig information for python
TestNetworkMsg.py: TestNetwork.h
	mig python -target=$(PLATFORM) $(CFLAGS) -python-classname=TestNetworkMsg TestNetwork.h TestNetworkMsg -o $@
CLEAN_EXTRA = TestNetworkMsg.py TestNetworkMsg.class TestNetworkMsg.java TestNetworkMsg.pyc
include $(MAKERULES)
migclean:
	rm -rf $(MIGFILES)

• 2. TestNetwork.h

"TestNetwork.h" defines necessary message structures for the wireless communication. Copy the code below into a txt file and save as "TestNetwork.h", or simply download it here: [TestNetwork.h]

#ifndef TEST_NETWORK_C_H
#define TEST_NETWORK_C_H
enum {
 AM_TESTNETWORKMSG = 0x05,
 AM_TESTNETWORKMSGG = 0x06,
 SAMPLE_RATE_KEY = 0x1,
 CL_TEST = 0xee,
 TEST_NETWORK_QUEUE_SIZE = 8,
};
#endif

• 3. TestNetworkAppC.nc

"TestNetworkAppC.nc" connects claimed application interfaces to interfaces that are defined in the hardware librare. Copy the code below into a txt file and save as "TestNetworkAppC.nc", or simply download it here: [TestNetworkAppC.nc]

/**
 * Testnework for TDMA simulation in Tossim. 
 * @author Bo Li
 * @version $Revision: 0.1 $ $Date: 2011/03/25 21:53:58 $
 */
#include "TestNetwork.h"

configuration TestNetworkAppC {
}
implementation {
  components TestNetworkC, MainC, ActiveMessageC;
  components new AMSenderC(AM_TESTNETWORKMSG) as Sender;  
  components new AMReceiverC(AM_TESTNETWORKMSG) as Receiver;  
  components new AMReceiverC(AM_TESTNETWORKMSG) as AMReceiver;
  components new TimerMilliC() as InjectionTimer;
  components SerialActiveMessageC as SerialAM;
  
  TestNetworkC.RadioControl -> SerialAM;
  TestNetworkC.SerialReceive -> SerialAM.Receive[AM_TESTNETWORKMSG];
  TestNetworkC.SerialSend -> SerialAM.AMSend[AM_TESTNETWORKMSG];
  
  TestNetworkC.Boot -> MainC;
  TestNetworkC.RadioControl -> ActiveMessageC;
  TestNetworkC.Send -> Sender;  
  TestNetworkC.Receive -> Receiver;
  TestNetworkC.AMReceive -> AMReceiver;
  TestNetworkC.InjectionTimer -> InjectionTimer;
}

Simulink Modeling in WCPS

Example

Application layer code:

* navigation
** mainpage|mainpage
** Special:Recentchanges|Recent changes

WSC Examples with WCPS

Wireless Building Control

Application layer code:

* navigation
** mainpage|mainpage
** Special:Recentchanges|Recent changes

Wireless Bridge Control

Application layer code:

* navigation
** mainpage|mainpage
** Special:Recentchanges|Recent changes

References

• B. Li, Z. Sun, K. Mechitov, G. Hackmann, C. Lu, S. Dyke, G. Agha and B. Spencer, "Realistic Case Studies of Wireless Structural Control," ACM/IEEE International Conference on Cyber-Physical Systems (ICCPS'13), April 2013.

• Z. Sun, B. Li, S.J. Dyke and C. Lu, "Evaluation of Performances of Structural Control Benchmark Problem with Time Delays from Wireless Sensor Network," Joint Conference of the Engineering Mechanics Institute and ASCE Joint Specialty Conference on Probabilistic Mechanics and Structural Reliability (EMI/PMC'12), June 2012.

• H. Lee, A. Cerpa, and P. Levis. Improving wireless simulation through noise modeling. In IPSN, 2007.

• P. Levis, N. Lee, M. Welsh, and D. Culler. Tossim: Accurate and scalable simulation of entire tinyos applications. In Sensys, 2003.

Contact the Authors:

Bo Li: boli@seas.wustl.edu