Menu
▾
▴
[Shox-cvs] SF.net SVN: shox:[2103] trunk/conf/examples
|
From: <dir...@us...> - 2009-09-13 14:52:18
|
Revision: 2103
http://shox.svn.sourceforge.net/shox/?rev=2103&view=rev
Author: dirk_held
Date: 2009-09-13 14:52:07 +0000 (Sun, 13 Sep 2009)
Log Message:
-----------
remove some text-files, after they have been moved to the wiki.
Removed Paths:
-------------
trunk/conf/examples/configuration-Intro.txt
trunk/conf/examples/layer-prog-Intro.txt
trunk/conf/examples/statistics-Intro.txt
Deleted: trunk/conf/examples/configuration-Intro.txt
===================================================================
--- trunk/conf/examples/configuration-Intro.txt 2009-07-23 12:28:30 UTC (rev 2102)
+++ trunk/conf/examples/configuration-Intro.txt 2009-09-13 14:52:07 UTC (rev 2103)
@@ -1,215 +0,0 @@
-This documentation gives a first introduction, how a configuration for a
-simulation using ShoX is done.
-
-1 locating and using sample configurations
-
-You can find several sample configurations in the "shox/conf" directory. Please open now
-the file "shox/conf/examples/OSRdynamic.xml". This configuration is used as main example
-in this documentation. To start a simulation, you have to add a new run-configuration to
-Eclipse (open menu "Run/Run Configurations..." and add a new Java Application). On the
-main-tab, you add the project shox (depending on your choice, when creating the shox
-project). The main class is "net.sf.shox.simulator.kernel.Simulator". In the Arguments-tab,
-you add the configuration, you want to run (use the configuration, you just have opened).
-To start the gui, use the main-class "net.sf.shox.visual.ShoX" with no arguments.
-
-2 sections of a configuration file
-
-There are sections, which define the size of the field, the initial placement
-of the nodes and how they move, if at all. Some sections describe the radio
-model and how collisions are detected or resolved. One sections describes
-the number of nodes and which layers each node uses. A logging section
-describes, how the log and the statistics are stored. There are some more
-sections, dealing with random numbers and the simulation time for instance.
-
-2.1 pseudo random number generator
-
-Although each class can create its own pseudo random number generator (PRNG), shox
-offers a central instance, which can be defined in the randomgenerator-section
-(lines 4-9). The example generator, which is the Mersenne-Twister, is currently the
-best choice. It will generate a random seed for each simulation run, which is written
-to the console on several occasions (at the beginning of a simulation, at the end and
-if the simulation is stopped due to a user exception). If you only use the standard
-random number generator, you can reproduce a run to a large extend by specifying this
-seed. Just uncomment the seed parameter in line 7 and enter the value. The PRNG offers
-several distributions you can choose from. The class AppRandomVoiceData in the directory
-shox/conf/examples offers some examples, how to create a special distribution. It was
-taken from another project, but can be easily adapted to your needs.
-
-2.2 size of the field, node positioning and movement
-
-The field-section (l. 10-12) defines the size of the rectangular network area, where the
-nodes are placed in. The used unit is the same as the unit used for the radio-model. The
-positions-section (l. 13-21) defines the class, which is used to generate the initial
-placement of all nodes. Alternatives to the used RandomStartPositions class are the
-GridPositionGenerator and the UniformStartPositions class. The first one positions the
-nodes on a grid and uses a tunable minimal distance, to set all nodes apart. Each line is
-filled before the next line is started. The second tries to position the nodes uniformly
-positioned in both directions, where the grid dimensions are as close as possible to
-sqrt(#Nodes) (for example are 100 nodes placed in a 10 times 10 grid). If this does not suit
-your needs, you can implement your own position generator by implementing a subclass of
-the StartPositionGenerator class. You can do this of course for all referenced classes too.
-Open the example implementation for the task and find its super-class and which methods to
-implement. Most aspects of the ShoX framework can be replaced this way.
-
-If you activate the nodefile section, you can specify a file, where the generated positions
-will be written to. If you omit the generated-section but supply the nodefile section, the
-positions from the nodefile will be used.
-
-The movementmanager-section (l. 22-30) defines if and how nodes move. The activated
-RandomWaypoint class is a good choice for moving nodes. The used parameters are described
-directly within the class. In general, this is done at the very beginning of each class,
-which has parameters. If you do not need/want moving nodes, just use the NoMovement-class.
-
-2.3 physical model and bit mangling
-
-The physicalmodel-section (l. 31-37) define the used physical model. This describes, how
-the propagation of the radio waves in the field is simulated. The bitmanglingmodel-section
-(l. 38-40) describes, what happens, if two or more radio-transmissions arrive at a receiver
-at the same time, or in other words determines, if a packet was received correct or not.
-
-ShoX offers currently the following bitmanglers:
-
-1.) NoBitMangling: As the name suggests, no packets are dropped. The use is not recommended
-in conjunction with a nontrivial MAC or PHY (like 802.11bg).
-
-2.) CollisionPacketMangler: Drops a packet, if at least one interference collides with it,
-no matter how weak this interference is. This means that the second parameter of a physical
-model, which describes the interference distance or threshold, should be better set to the
-value of the first parameter, if a physical model is used, where no attenuation of the signal
-is determined.
-
-3.) PeakNoiseMangler: Drops a packet, if a colliding interference is found, where the signal
-to noise ratio (SNR) is below a tunable level, for example 2. Thus if at a time multiple
-interferences collide with the transmission, where each interference is too insignificant,
-but the sum would be significant, the result is not accurate. This simplification drastically
-reduces the needed effort, to handle the reception of a transmission. (Depends on a physical
-model, where the attenuation is somehow determined)
-
-4.) AddedNoiseMangler: Adds all current interferences up and drops the packet, if the SNR
-drops at any time below a tunable level. (Depends on a physical model, where the attenuation
-is somehow determined)
-
-Useful combinations of a physical model with a bit mangler:
-
-a.) SimplePhysics + NoBitMangling
-
-All nodes can reach each other and are in the same collision set.
-This combination is not recommended, when used with a nontrivial MAC.
-
-b.) UnitDisk + CollisionPacketMangler
-This is probably the most basic model. The UnitDisc model describes a disc with the
-radius "reachableDistance", where all transmissions reach all nodes within this range.
-
-c.) RandomizedUnitDisc + PeakNoiseMangler|AddedNoiseMangler
-
-It offers a randomized decision, if a interference occurs and decreases the RSS
-linearly beyond the reachableDistance down to zero at the interferenceDistance.
-
-d.) FuzzyDisc + CollisionPacketMangler?
-
-No much information available here.
-
-e.) IndoorAttenuationFactor + PeakNoiseMangler|AddedNoiseMangler
-
-The IndoorAttenuationFactor class uses a map to calculate the attenuation of the
-transmission for each passed obstacle.
-
-f.) VariableDisc + PeakNoiseMangler|AddedNoiseMangler
-
-Simulates a quadratic decaying radio signal with two thresholds. One for the minimum
-needed signal strength at which a packet is still received successfully, the other
-for the signal strength at which a transmission still interferes with other signals.
-
-The easiest way to get some more realism, compared to the
-example, is choice c or f.
-
-2.4 nodes and layers
-
-It is possible, to exchange several layers for all nodes. There are the physical layer,
-the MAC layer, the logical link layer, the network layer, the operating system layer
-and the application layer. The example specifies only the physical, the MAC, the
-network and the application layer. The remaining layers are set to dummy implementations,
-which only forwards all received packets up or down the layer-stack, along the direction
-of the packet.
-
-The count section in line 36 specifies the number of nodes for the simulation.
-
-2.4.1 physical layers
-
-Currently only the dummy and the 802.11bg implementation are available. Which are the
-PhysicalDebug and the PHY_802_11bg class. If you do not care about a MAC or a physical
-layer and thus do not specify them, the PhysicalDebug class is used. If you wand to
-implement a new (for example TDMA) MAC on top of the 802.11bg hardware, specify the
-PHY_802_11bg class. This class is of course needed, if the 802.11bg MAC is used.
-
-2.4.2 MAC layers
-
-Likewise to the physical layer, only the dummy and the 802.11bg implementation are
-currently available. The 802.11bg MAC of course needs the 802.11bg physical layer and
-the MACdebug class works with the PhysicalDebug class.
-
-2.4.3 logical link layers
-
-There are several descendants of the LogLinkLayer class, like OBMStatisticLayer,
-StaticGridBackboneLogLinkLayer class, LogLinkDebug class and the LogLinkPosition class.
-The LogLinkDebug class is again the dummy implementation, which is used, if nothing else
-was specified. For the remaining classes, not much information is available. The the source
-of each class, where a short comment at the beginning and the comment of the parameters may
-give you a hint about the function.
-
-See the shox/conf/examples/ll directory for an example implementation of a layer, which
-aggregates multiple packets to the same receiver to a larger one, to reduce the overhead,
-when many packets are sent. To do so, small packets are delayed for some time and combined
-with other small packets for the same receiver, until they are sent. Although this is not a
-logical link task, this class can be used as an example, how to implement a layer and how to
-do logging and statistics.
-
-2.4.4 network layers
-
-There are several implementations of a network layer:
-
-a.) NetworkDebug: the dummy implementation, if nothing is specified. No routing
-is performed here, so this implementation actually makes not much sense.
-
-b.) OptimalSourceRouting: Used in the example and determines the next hop by
-questioning an oracle. This class is applicable for static and for moving nodes
-and is the real dummy-implementation, since it performs real routing.
-
-c.) AodvNetworkLayer: implements the aodv protocol.
-(timing parameters seem to be simulation steps, instead of seconds, thus be
-careful, when you change the resolution of the simulation to another value)
-
-d.) AodvmNetworkLayer: currently incomplete multipath variant of the aodv implementation.
-
-e.) Threephase: implements a geographic routing scheme.
-
-If you do not care about routing, or want to eliminate the influence of routing
-on your personal layers, you want to analyze, use b. Implementation a makes
-not much sense for nontrivial setups, but d and e should be usable.
-
-2.4.5 operating system layers
-
-If you do not care about multiple ports and services, use the dummy implementation,
-which is NullOperatingSystemLayer (or just do not specify an operating system layer).
-The BasicOperatingSystemLayer class offers port mapping.
-
-2.5 logging and time
-
-Each class can have its own logger object, to print messages with a selectable
-priority. Have a look at the Aggregator class in line 51, where a LOGGER object
-is created and how it is used. Have a look at /shox/conf/log4j.properties, where
-you can specify the verbosity-level for each class, which uses a Logger object.
-
-The whole simulation can be recorded and replayed within the gui. During each run
-arbitrary statistics can be created and later on visualized within the gui. To do so,
-set logging to true (line 59) and add a file-name for the parts, you need in line 60
-and 61, where history refers to the simulation-replay file and statistics to the file,
-where all statistics are written to. The first implementation, which stores the data,
-used XML, which has lead to LARGE files. The current compact file logger is much more
-economical. To reduce the number of entries to the history even more, you can add
-filters (see lines 67 to 77).
-
-The last section simulationtime (line 81) is used, to specify the granularity of the
-simulation time and the total duration in seconds. There may be unexpected side effects,
-when changing stepspersecond, thus just keep it as is.
-
Deleted: trunk/conf/examples/layer-prog-Intro.txt
===================================================================
--- trunk/conf/examples/layer-prog-Intro.txt 2009-07-23 12:28:30 UTC (rev 2102)
+++ trunk/conf/examples/layer-prog-Intro.txt 2009-09-13 14:52:07 UTC (rev 2103)
@@ -1,148 +0,0 @@
-0 quick overview
-
-The following text will refer to the OptimalSourceRoutingLayer class (OSRL), which is located in
-net.sf.shox.simulator.node.user is a short example, how to implement a (network) layer. The most
-basic methods a layer has to implement are the lowerSAP (service access point) and the upperSAP
-(the application layer has no such thing). All packets go through these calls. Each layer also
-has to listen to (own) wakeup calls. The central hub for these events is the processWakeUpCall
-method. All timer events for example go through this call. If you need to configure your layer
-depending on the configuration, the initConfiguration method is the place to go. The configuration
-object contains some external values, like simulation duration or node count. All the parameters,
-which you have created, by marking your variables with a @ShoXParameter tag, a filled now. In most
-cases the processEvent calls with a Initialize, StartSimulation or Finalize event are used too, to
-take action in the respective phase of the simulation run. No layer should send packets prior the
-StartSimulation event. Any final statistics for example must be collected, when the Finalize event
-is received. A layer may have some states, which may me exported or even may be modified by other
-layers. To do so, the methods getState and setState are used.
-
-1. some predefined variables and methods, to use
-
-All nodes have a unique ID and each layer has an unique LayerType. Together they form the Address
-of this layer at this node. All descendants of the Layer-Class have access to the protected variables
-layerType, id, sender (as combination of id and layerType) and node. Whenever a packet is to be
-created, or the id of a node is needed (to print a log-message for example), these variables can be
-used. If you want to print log-messages to the console, you can add a Logger to your class, as it is
-done in most classes at the beginning (see OSRL @ line ~57). The node can return the local time
-with the getCurrentTime() method. No inaccurate clock is simulated here, thus this the accurate
-simulation time. The methods node.getPosition() gives access to the current real position. Setting
-the position is preferable done by a movement-manager or a position-generator, which you may
-want to implement yourself (see net.sf.shox.simulator.movement). The method node.getRandom()
-returns the global pseudo random number generator, which yields random numbers with the next*()
-calls. To resolve the neighborhood directly, without having to detect them first, using extra packets,
-use the node.getNeighbors(), getNeighborCount(), or resolveNeighbor() methods. Although there are
-other public methods, which deal with neighbors, they are only used internally.
-Although it may be useful, to directly access the MAC-Layer of of a neighbors node, to check, if a
-packet has reached this node, to have exact statistics, lots of nasty things can be done this way.
-It is up to you, how you use so-called god-knowledge or god-methods, since in reality one node
-cannot directly access other nodes inner state.
-
-2. The packet-class
-
-Each packet has its own header, a current direction (up or down the layer-stack), a timestamp of the
-creation time and a pointer to the inner packet of the next higher layer. The creating layer uses the
-Packet(Address sender, NodeId receiver) constructor to create the innermost layer, where the header is
-actually the payload of the packet. Use NodeId.ALLNODES as broadcast-address, if needed. The other two
-constructors are used down the layer-stack, to wrap the layer-specific header around a packet, which
-was received from a higher layer. Only the network-layer may specify a new receiver, which is the next
-hop along the path to the final receiver.
-
-here is an extract of the methods of the packet class:
-
-- isTerminal() : returns true, if there is no inner packet.
-- flipDirection() : used on network layers, to send a to be forwarded again down the layer stack.
-- getDirection() : the current direction along which this packet is currently traveling (up/down)
-- getEnclosedPacket() : used to unwrap a packet, before it is forwarded up to the next layer.
-- getEnclosedPacket(LayerType) specify the layer. to extract .
-- getHighestLayerType(): the layer-type, which originally has created this packet.
-- getHighestEnclosedPacket(): return the packet of the innermost layer, which originally created it.
-- getLayer(): return the layer of the packet.
-- <T extends Packet> T containsPacketType(Class<T> packetClass): alternative to getEnclosedPacket(LayerType)
- which saves some casts.
-- getHeaderLength(): return the length of the header of this layer in bits, if the annotations are not used.
-- setHeaderLength(int bits) set the number of bits, which are used for the header of this layer.
-- getTotalPacketSizeInBit(): sum up the total size of the headers of all layers including the payload.
-- setTime(double currentTime): is set by the simulator at the creation of this packet.
-- getTime(): return the previously set timestamp.
-- getMetaInfos(): additional informations for a packet, which should not be sent to next node, but are
-needed further down or up the layer-stack.
-
- There are some other methods, which mainly deal with debug- or statistic-informations. It is
- possible, to request the nodes, which successfully have received a packet and which where in
- transmission range, but did not receive it successfully. Use setRequestReceiverInformation(true),
- to request information about the receiving nodes. This is of course god-information and is only
- meant for debug- or statistic-purposes.
-
-3. The upperSAP() (service access point)
-
-For each layer, but the Application-layer, the basic concept is to receive packets from the next
-higher layer via the upperSAP (service access point), wrap the received packet p with a header
-of this layer and send it down to the next lower layer with sendPacket(p2) method. This is done,
-by generating a descendant of one layer-specific super-class and creating a new packet p2 of
-this class and supplying it with the packet p of the next higher layer. The physical layer sends
-then a physical packet to the pseudo-layer AirModule, which handles the physical transmission
-to all affected nodes.
-
-4. The lowerSAP()
-
-Each packet, which reaches a node, is fed from the AirModule to its physical layer at its lowerSAP(),
-if the nodes radio is currently listening. A physical layer mainly drops invalid packets and forwards
-the enclosed packet up to the MAC, using sendPacket(). Since the direction of the packet was
-toggled, when going through the AirModule, the packet is now sent up the layer-stack.
-
-5. The event hub processWakeUpCall()
-
-To send (delayed) events, you need to create a descendant of the WakeUpCall-class, to create
-events of your own type. You can send your events with the sendEventUp(), sendEventDown(),
-sendEventSelf() or sendEventTo(layerType) call. These methods forward an event up to the next
-higher layer, or down, or to this layer, or you specify the destination layer. In order to process
-received events in the processWakeUpCall method, you need to distinguish between all types of
-events, which may arrive here. Check for the most specific types first.
-To return the result of a operation for a packet up to the layer, which has initially created
-this packet, a so-called CrossLayerEvent is used. The most important event is here the
-TransmissionFailedEvent event, which is issued, when a packet was not successfully sent after
-a fixed maximum number of retries failed (see MAC_IEEE802_11bg_DCF.java at line ~704 for example).
-Even if a layer does not care about CrossLayerEvents, they still need to be forwarded up. See the
-method processWakeUpCall in line ~239 ff. of OSRL, how to do that.
-
-6. Accessing the configuration: initConfiguration()
-
-To access the configuration, use the getConfig()-method. It is best practice, to use real seconds
-for all time-parameters, which are stored in a configuration. Then convert these values to internal
-simulation-steps, using the getConfig().getSimulationSteps(seconds) method. The inverse method
-getConfig().getSeconds(simulationSteps) converts these values back to seconds.
-
-7. The Initialize, StartSimulation or Finalize events
-
-Doing the initialization, when processing the Initialize event is rather obsolete, apart from the
-neighborhood information, which is now ready too. Thus this is the latest time, to setup all needed
-structures. When the StartSimulation event is processed, each layer may start with sending
-packets, for example beacons, to explore the environment. If you have implemented your traffic
-generating engine in the application layer, it is time, to start to send your traffic. When the
-Finalize event arrives, final actions have to be performed, since this is the last call. See OSRL
-@ line ~143, where the Finalize event is processed, how the last call to this method is detected.
-Although testing for the id == #Nodes would do too, this is more safe, since the order of calls
-may change in the future.
-
-8. getting and setting layer states
-
-The node object of each layer offers the two methods getLayerState() and setLayerState().
-The first method returns an state-object, which is specific for the requested layer. This object
-contains the current state of this layer at this node. It may contain some tunable variables,
-which could be send to the layer with the setLayerState() method. See the 802.11 MAC
-implementation in net.sf.shox.simulator.node.user.MAC_IEEE802_11bg_DCF for the use of
-the getLayerState() method. Setting a state is rather rarely done in higher layers than the
-MAC-Layer. The layerState of the application-layer is used to form a return code. The enum
-ApplicationState offers the values CREATED, WAITING, RUNNING, FAILED, DONE. If the value is
-not set to DONE before the end, the value is set to FAILED. At the end, the number of done and
-failed nodes is printed. This just for your quick information at the end.
-
-9. dumping link- and node-states
-
-Each node can dump arbitrary named values as the current link- or node-state. These values are
-stored in the log-file and could be visualized in several ways after the simulation. Each node
-and link has certain attributes, which could be used, to visualize one named value, which was
-stored as link- or node-state. See OSRL at lines ~60-97 for some wrapper routines, which can write
-a link- or node-state. After completing a run, start the GUI and open the file history.compact
-in the shox directory with the "File/Open Log File ..." menu. After parsing the data, a new tab
-"Monitor" should be created. The menu "Mapping/Config Mapping ..." offers the possibility, to
-assign certain values to certain visualizations, like node color, node/link-label.
Deleted: trunk/conf/examples/statistics-Intro.txt
===================================================================
--- trunk/conf/examples/statistics-Intro.txt 2009-07-23 12:28:30 UTC (rev 2102)
+++ trunk/conf/examples/statistics-Intro.txt 2009-09-13 14:52:07 UTC (rev 2103)
@@ -1,93 +0,0 @@
-/*
- This code snipped is intended to show, how statistics could be created. The values are stored
- in two ways: as entry in the file statisticsdefault.compact and in a cvs file "statistics.csv",
- using the FileEvaluationLogger class. You need to enable logging in the configuration file, to
- actually create the file statisticsdefault.compact. Do this by adding the section logging:
-
- <logging>
- <log>true</log>
- <nameHistoryFile></nameHistoryFile>
- <nameStatisticsFile>statistics</nameStatisticsFile>
- <logClass>net.sf.shox.debug.compactlogging.CompactFileLogger</logClass>
- </logging>
-
- The history file is ommitted here, to save space and time.
-*/
-
-Look at the class net.sf.shox.simulator.util.StatUtil. This class can be used, to write statistic values
-to the ShoX statistics-file, which can be displayed after the run is completed. All those statistics are
-assigned to node "1", no matter, which node uses this class. Actually should only one node use this class.
-Additionally could all values also be written to a CSV-file of your choice. To organize the creation of
-statistic-value creation, create a StatUtil-object, establish a timer, which is called once a second or
-so for one node, where a createStatistics(false) method is called. Call createStatistics(true) when the
-Finalize-event is processed in the method "protected final void processEvent(final Finalize end)" of your
-application. Thus add/correct the following lines to the appropriate places of your application-layer:
-
- // were the variables are declared
-
- private StatUtil su = null;
-
- ...
-
- // were they are initialized -> like in "protected final void processEvent(Initialize init)"
-
- if (id.asInt() == 1) {
- choose: su = new StatUtil(<the number of statistic values>);
- or: su = new StatUtil(<the number of statistic values>, "statistics.csv or the like", ' ');
- // you may choose another separating char, like ';', but not '_'
-
- AppTimerEvent timer = new AppTimerEvent(getConfig().getSimulationSteps(1.0)); // interval = one second
- sendEventSelf(timer);
- }
-
- ...
-
- // near the beginning of "public void processWakeUpCall(final WakeUpCall wuc)"
-
- if (wuc instanceof AppTimerEvent) {
- createStatistics(false);
- sendEventSelf(wuc);
- } else ...
-
- ...
-
- // Add to "protected final void processEvent(final Finalize end)"
-
- if (id.asInte() == 1) { // or the node with the highest id, if some global statistics are not yet created.
- createStatistics(true);
- }
-
- ...
-
- private void createStatistics(boolean finalize) {
- // add your calls to create statistic-values here like...
- // this tiny example adds four values, which needs to be added to the constructor of the su-object.
-
- int i = 42;
- su.statInt("int-label", i);
-
- double x = 4711.0815;
- su.statDouble("double-label", x);
-
- x = 0.42;
- su.statPercent("percent-label", x);
-
- x = Util.now(); // it is a simulation-time value, no need to convert it to seconds.
- su.statTime("time-label", x);
-
- // this is of course not needed, if you did not add a CSV-file
-
- if (finalize) {
- su.closeCSVfile();
- }
- }
-
- ...
-
- // well, you need still a AppTimerEvent-class, like
-
- public class AppTimerEvent extends WakeUpCall {
- }
-
- // or use the net.sf.shox.simulator.event.AppEvent-class directly and select by a type of your choice.
-
\ No newline at end of file
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
