forked from srmq/MobileSim
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.html
911 lines (910 loc) · 71.3 KB
/
README.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta name="generator" content="pandoc" />
<title>MobileSim</title>
<style type="text/css">code{white-space: pre;}</style>
</head>
<body>
<div id="header">
<h1 class="title">MobileSim</h1>
</div>
<div id="TOC">
<ul>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#installation">Installation</a></li>
<li><a href="#how-to-get-started">How to get started</a></li>
<li><a href="#notes-limitations-and-future-plans">Notes, Limitations, and Future Plans</a></li>
<li><a href="#internal-simulation-mechanism-and-models">Internal Simulation Mechanism and Models</a></li>
<li><a href="#advanced-usage">Advanced Usage</a></li>
<li><a href="#robot-protocol-support">Robot Protocol Support</a></li>
</ul>
</div>
<h2 id="introduction">Introduction</h2>
<div class="figure">
<img src="MobileSim_screenshot.png" alt="Screenshot of MobileSim with three robots" />
<p class="caption">Screenshot of MobileSim with three robots</p>
</div>
<p>MobileSim is software for simulating mobile robots and their environments, for debugging and experimentation with <a href="http://robots.mobilerobots.com/wiki/Aria%20ARIA">ARIA</a> or other software that supports Adept MobileRobots platforms.</p>
<p>MobileSim is based on the Stage library, created by the <a href="http://playerstage.sourceforge.net%20Player/Stage/Gazebo%20project">Player/Stage project</a>. Stage and MobileSim are free software, distributed under the terms of the GNU General Public License: see <a href="LICENSE.txt">the full license</a> for details.</p>
<p>MobileSim converts a MobileRobots/ActivMedia map (a .map file, created by Mapper3™, Mapper3-Basic, or other means) to a Stage environment, and places a simulated robot model in that environment. It then provides a simulated Pioneer control connection accessible via a TCP port (similar to the real Pioneer's serial port connection). ARIA is able to connect to TCP ports instead of serial ports (ArRobotConnector, for example, automatically tries TCP port 8101 before the serial port).</p>
<p>MobileSim (powered by Stage) has the following features and device models. Device model parameters may be customized in a configuration file, or new models may be defined based on existing models.</p>
<ul>
<li>Various models of MobileRobots/ActivMedia differential drive mobile robot bases (Pioneer 3 DX and AT, PowerBot™, AmigoBot™, PeopleBot™, PatrolBot®, Seekur®, Pioneer 2, Pioneer 1).</li>
<li>You can define custom models of differential drive or omnidirectional robots, laser and sonar, defined either as a Stage model definition, or by loading an Aria parameter (.p) file.</li>
<li>Sonar range sensor model</li>
<li>Laser range sensor (SICK LMS-200) model</li>
<li>Robot odometry pose estimation (with cumulative error)</li>
<li>Multiple robots (good performance is possible on a fast computer with more than 25 robots)</li>
<li>Evironment and obstacles are loaded from a MobileRobots/ActivMedia/ARIA map file; use the same map with ARNL/SONARNL or your own software.</li>
<li>Interactively move robots and obstacles (with customized map file, see below)</li>
<li>Objects (robots or obstactles) may be configured to be detectable only by some sensors</li>
<li>Objects (robots or obstacles) may be set as "highly reflective" for special detection by the laser range sensor</li>
<li>Save image "snapshot" of simulation or save a sequence of images for making movies.</li>
<li>Map files may be reloaded at run time</li>
<li>Robots may be interactively repositioned through the GUI or by a command from client software</li>
<li>Client software may send log messages to MobileSim. Log messages are timestamped and displayed both the GUI and console or log file, with optional HTML formatting.</li>
<li>Visualization options for sensors, robots and obstacles, such as drawing robot "trails" to show history of motion, color, diagnostic values/visualization, and visualizations for debugging the simulator itself.</li>
<li>Configurable space and time resolutions.</li>
<li>Full source code included under the GPL for understanding the simulation implementation, customizing and improving it, or even adapting MobileSim's ARIA communication protocol layer for other simulators.</li>
</ul>
<h2 id="installation">Installation</h2>
<p>To install MobileSim on Windows, run the executable self-installer.</p>
<p>To install MobileSim from either the RPM or Debian (deb) package, use your system's appropriate installation tool (<code>rpm</code> on RedHat, SuSe, etc. and <code>dpkg</code> or Synaptic ("Add downloaded packages") on Debian, Ubuntu, etc.). The RPM was built on RedHat 7.3, and the Debian package was built on Debian 3.1 (sarge) for i386 (32-bit). MobileSim requires the GTK 2.0+ libraries on RedHat, and GTK 2.6+ on Debian. It also requires libstdc++ 2.2 for libc6. (These libraries are standard parts of most Linux installations, but if they are missing you may have to install packages which provide them). If you are running amd64 or ia64 Debian, try installing the <code>ia32-libs-gtk</code> and <code>ia32-libs</code> packages using <code>apt-get</code>, and then installing the MobileSim package with the <code>--force-architecture</code> option to <code>dpkg</code>.</p>
<p>To build MobileSim from source code, obtain the "MobileSim-src" tar/gz archive from <a href="http://robots.mobilerobots.com/wiki/MobileSim%20MobileSim%20web%20page">http://robots.mobilerobots.com/wiki/MobileSim</a> and follow the instructions in the README.src.text file found inside.</p>
<h2 id="how-to-get-started">How to get started</h2>
<p>To simulate a robot you need a map file containing lines for walls. A map file with lines can be created using a recent version of Mapper3 or Mapper3-Basic (See [robots.mobilerobots.com][site]) or by other means. See the <a href="../Aria/docs/index.html">ARIA Reference Documentation</a> for the <code>ArMap</code> class for a full description of the format, or refer to <code>columbia.map</code> or <code>AMROffice.map</code>, distributed with MobileSim, for an example.</p>
<p>MobileSim may be launched from the Start menu (Windows), or from the Gnome or KDE menu (Linux), or from the command line (any platform).</p>
<p>Run MobileSim from a command line prompt like this:</p>
<pre><code>MobileSim</code></pre>
<p>or, to skip the initial dialog by specifying a map file and robot model to create on the command line:</p>
<pre><code>MobileSim -m *<map file>* -r *<robot model>*</code></pre>
<p>For example:</p>
<pre><code>MobileSim -m columbia.map -r p3dx</code></pre>
<p>The parameters are optional. The default robot model created, if -r is not given, is "p3dx". Some additional robot models include "p3at", "powerbot", "peoplebot", "patrolbot-sh", "seekur", and "amigo".</p>
<p>To create multiple simulated robots, use -r multiple times, naming the robots after the model type, seperated by a colon, if you wish:</p>
<pre><code> MobileSim -m columbia.map -r p3dx:robot1 -r p3dx:robot2 -r amigo:robot3</code></pre>
<p>If you are working with many robots, it can be inconvenient to create them all at MobileSim startup. If you use -R instead of -r, then a new robot will be created on demand for each client that connects, and destroyed when the client exits. (So the robot's state is not preserved.)</p>
<p>More command-line options are described below.</p>
<p>If you run MobileSim with no command line options, or from the desktop menu, you may select the map and one robot model from a dialog box. Or, you may choose to use no map (but note that in this case, the usable universe is limited to 200 x 200 meters -- gray area indicates the edge.)</p>
<p>Example maps are included with MobileSim. On Linux, you can find these files by navigating from the root file system to <code>/usr/local/MobileSim</code>. On Windows, these maps are in <code>C:\Program Files\MobileRobots\MobileSim</code>. <code>columbia.map</code> included with MobileSim is equivalent to <code>columbia.map</code> included with ARNL.</p>
<p>A window will appear, displaying your map environment and robot(s). The robot will start at a home position in your map, if present, or at the center of the map. The robot's body is drawn based on the aproximate length and width -- including wheels -- of the model selected. You can pan in the window by holding down the right mouse button, or mouse button with the Shift or Control key and dragging. You can zoom with the mouse scroll wheel, or by holding down the middle mouse button or left mouse button with the Alt or Option key, and dragging towards or away from the center of the circle that appears.</p>
<p>The robot may be moved by dragging it with the left mouse button and rotated by dragging it with the right mouse button, or while holding down the Shift or Control key. Note that this will update the robot's true pose, but <em>not</em> its odometry -- it is like picking up the robot off the ground and carrying it to a new location.</p>
<p>You can turn on device visualizations using the View menu. Ranger or Sonar: if a client program has connected and enabled the sonar, sonar field centers will be drawn as grey lines. Laser: If a client program has enabled the laser rangefinder, its range will be drawn as a light blue field. Position: Axes are drawn for the robot's odometry coordinate system, and its true pose, odometric pose, and current velocity are displayed.</p>
<p>A snapshot or sequence of snapshots of the window can be saved as a bitmap file to disk with the Export item in the File menu.</p>
<p>The lower log message pane displays information and warning about what the robots are doing (some commands will result in a log message, but not all). <code>SIM_MESSAGE</code> commands also display messages here. The statusbar pane below the log message pane displays, from left to right: the total time since the simulator started; the ratio of real time per update step and simulation time, indicating how close to real-time (1.0) the simulation is running; the total number of "subscriptions" in the simulation (one per each robot plus one per each device being accessed); and the MobileSim and stage version numbers.</p>
<p>Once running, a program can connect to the simulator via TCP port 8101, and use the same protocol on that TCP port as it does with a real robot over its serial port link. Any ARIA-based program that uses ArRobotConnector or ArTcpConnection will do this automatically. You can specify an alternate port number with the -p option. If multiple robots were requested with multiple -r options, each additional robot will use the next port number (i.e. 8102, 8103, etc.). For these additional robots, you will have to specify the port number when running its ARIA program, usually using the -rrtp (-remoteRobotTcpPort) command-line option.</p>
<p>A tool called <code>convertBitmapToArMap</code> is available in the ARIA utilities and in the MobileSim source code to convert a PNM format bitmap image to an ArMap .map file. On Linux, first install libnetpbm::</p>
<p>sudo apt-get install libnetpbm</p>
<p>Then you can build convertBitmapToArMap using make:</p>
<p>make convertBitmapToArMap</p>
<p>Run with <code>-help</code> for info:</p>
<p>./convertBitmapToArMap --help</p>
<p>A tool called <code>convertSfWorldToMap</code> is also available in ARIA's collection of utility and example programs to convert a Saphira .wld file to a .map, as well as a tool called <code>addSfWorldLinesToMap</code> for importing lines into a .map from a .wld.</p>
<h2 id="notes-limitations-and-future-plans">Notes, Limitations, and Future Plans</h2>
<p>The goal of Stage and MobileSim are to provide an efficient and sufficient simulation of multiple robots. While we have modified Stage to add some features and additional behavior (such as basic sensor noise), the simulation remains simplified. Don't forget to test your code on a real robot. See below for notes on the internal simulation mechanism and robot and sensor models.</p>
<blockquote>
<p>"All models are wrong. Some are useful." --George E. P. Box</p>
</blockquote>
<p>However, since the full source code for MobileSim and Stage are available (in the "MobileSim-src" package available from the <a href="http://robots.mobilerobots.com/wiki/MobileSim%20MobileSim%20web%20page">MobileSim webpage</a>), it is always possible to add new models or modify existing models to simulate any particular properties you need. Stage is not hard to understand and modify. If you need any help, ask on the aria-users mailing list, or the Player/Stage mailing list. If you do make any modifications that you think others would find useful, you may post them to aria-users, or send them to [email protected].</p>
<h4 id="a-note-about-data-communications-channels">A note about data communications channels</h4>
<p>On a real robot, ARIA may be communicating with different devices over separate communications channels. For example, ARIA communicates with the robot microcontroller over one RS-232 serial port, with a SICK LMS-200 laser rangefinder over a different RS-232 serial port, simultaneously using two different threads (one contained in ArRobot, the other in ArLMS200 which is a subclass of ArThreadedRangeDevice). Other additional devices may use additional parallel communications channels such as serial, USB and ethernet connections.</p>
<p>However, ARIA communicates with MobileSim over only one TCP socket connection. Therefore all communications with both the simulated robot and simulated devices must occur on this one channel, the same channel as the robot connection. ARIA's Connector classes detect MobileSim and use the appropriate code to handle data transfer with devices via the original "robot" TCP connection to MobileSim. Be aware of this when structuring programs; for example, laser data will not be received unless the ArRobot connection is active and running (using either <code>ArRobot::runAsync()</code> or <code>ArRobot::run()</code>).</p>
<h4 id="additional-notes">Additional notes:</h4>
<ul>
<li>See below for details on supported commands and specific known problems with the ARCOS/AROS/P2OS command emulation.</li>
<li>Sonar reflection is not modeled</li>
<li>Several devices are not available yet, including grippers, arms, general pan-tilt units, IR sensors, bumpers, analog or digital I/O ports, or video cameras.</li>
<li>MobileSim is somewhat graphics intensive and may compete with e.g. MobileEyes for graphics resources, especially on older computers, VMs, or other systems with limited graphics resources. Graphics display is not fully optimized yet.</li>
<li>While it is possible to make the simulation run faster (or much slower) than near "real time", it is not well tested how this affects clients. Many clients (including those using ARIA) have timeout limits based on the real system time (it is possible to configure most of ARIA's timeout limits, though. See reference documentation or ask the aria-users group).<br />
Clients also may not be able to process packets fast enough if the simulation runs much faster than real time, resulting in buffering of data and possibly loss of data.</li>
</ul>
<p>Future plans for include better sonar model, simulating additional devices, and various user interface features for creating new simulated robots, loading maps, and tweaking their properties. If you have any requests or would like to help add features, please join the discussion on the aria-users mailing list.</p>
<h2 id="internal-simulation-mechanism-and-models">Internal Simulation Mechanism and Models</h2>
<p>The simulation loop attempts to run at a fixed real-world time interval, corresponding to a fixed simulated-world time interval. In most cases, each simulated time interval would ideally equal the real (system) time taken to perform that interval. This ratio is monitored and a short running average is displayed in the bottom of the MobileSim GUI window, and is also available from the <code>SIM_STAT</code> packet. It should normally be at or close to 1.0 most of the time. (The desired ratio can be adjusted, but will cause problems with most software).</p>
<p>At each iteration, the Stage simulation engine checks for GUI input (if GUI is enabled), then updates state of each simulated robot, sensor, and other device in the simulation -- it is at this stage that the robot is moved if moving, the environment is searched to determine sensor readings, etc. (See below for some deatils.) Then the GUI display (if enabled) is updated. The simulation update interval is configurable. The default rate is 100ms.</p>
<p>Client communications are also done at a given interval (100ms by default). For each robot, data is sent if a client is connected to that robot, according to the Pioneer protocol. This includes its odometric position estimate, miscellaneous state, and, if enabled, simulated sonar and laser data.<br />
Commands are read from the client software (if any were sent), and stored for the appropriate Stage device model to handle in the next iteration of the simulation loop.</p>
<p>Each robot, and each sensor or other device on each robot, is simulated by a <code>model</code> object. The code for these models can be found in the <code>stage/src</code> subdirectory of the MobileSim source code.</p>
<h4 id="simulation-environment">Simulation environment</h4>
<p>The contents of the simulated world are read from a map file (ArMap format, same as used by Mapper3 and other AMR software). The ArMap file contains obstacle data given as points and/or lines which will be sensable by all sensors, and with which robots can also collide. It is also possible to represent simple shapes in the map file which will only be present in the simulator (and are not used by ARNL for localization or planning). These objects may be configured as visible or invisible to different sensor types, and as subject to collisions by other models (i.e. robots) or not. See below for details.</p>
<p>In addition, the shape of all simulated robot models are also present in the environment, and subject to collision and sensing by other robots.</p>
<p>The simulation environment is represented with a minimum resolution, which is by default 2 cm. (This can be adjusted with the <code>--resolution</code> command-line argument, see below for details.)</p>
<h4 id="position-model-a-movable-robot">position model, a movable robot</h4>
<p>A mobile robot that can move within the world. The robot may be differential-drive (two degrees of freedom, capable of translational and rotational motion), or omnidirectional (three degrees of freedom, capable of translational, lateral or rotational motion). Motion can be commanded via desired velocities in each axis (velocity control, from <code>VEL</code>, <code>TRANSVEL</code>, and <code>RVEL</code> comands), or discrete changes in position may be commanded relative-position control from <code>MOVE</code> and <code>DHEAD</code> commands, or absolute heading from <code>HEAD</code> command). In addition, clients can request artifically dropping the robot at any new position in the world.</p>
<p>The code implementing the position model can be found in the MobileSim source code in <code>stage/src/model_position.c</code>.</p>
<p>At each simulation loop, the position model is updated according to the most recently received velocity commands. Velocity is controlled on three independent axes: translation (robot local X), lateral translation (robot local Y, non-differential drive robots only) and rotation (robot local Theta). The position model determines the currently desired velocities on each axis of motion (X, Y (seekur robot only), and Theta). This is clamped according to previously set maximum speed parameters. Previously set acceleration or deceleration parameters and the duration of the simulated loop iteration are then used to determine an increased or decreased velocity from the robot's current velocity, and a potential new position is projected from the current position using these velocities. This is followed by collision checking, and then an update of the simulated odometric pose estimate.</p>
<p>If a relative distance translation (<code>MOVE</code>) command is active, then a velocity proportional to the remaining distance and the configured maximum velocity is used. If the robot has already moved the commanded move distance however, then desired velocity is set to 0. The desired velocity will later be limited according to maximum speed configured.</p>
<p>If a translation velocity command (<code>VEL</code>) is active instead, then this value is used as the desired velocity.</p>
<p>If the robot is omnidirectional (not differential drive), then the same is done for Y (<code>LATVEL</code> commands velocity in Y. There is no command in the Pioneer protocol for relative distance on Y.)</p>
<p>If an absolute heading command (<code>HEAD</code>) is active, then a rotational velocity proportional to the difference from the current heading is used. If the robot has already rotated to the commanded heading however, then no rotational velocity is desired. The desired velocity will later be limited according to maximum speed configured.</p>
<p>Relative heading commands (<code>DHEAD</code>) are converted to absolute heading commands when recieved based on the robot's current heading at the time the command is received.</p>
<p>If a rotational velocity command (<code>RVEL</code>) is active instead, then this value is used as the desired rotational velocity.</p>
<p>Next, all desired speeds as specified or calculated above are limited by maximum upper limit parameters. These are set separately by software clients using <code>SETV</code> and <code>SETRV</code> commands (or initial defaults specified in the model definitions in <code>PioneerRobotModels.world.inc</code>.)</p>
<p>Next, acceleration and deceleration parameters are used to ramp the robot's current velocities up or down towards the desired velocities. Acceleration and decelaration parametrs are set separately by clients using <code>SETA</code> and <code>SETRA</code> commands (or initial defaults from the model definitions are used). (A client may also specify a temporary override deceleration value via the <code>ESTOP</code>/<code>QSTOP</code> commands. Deceleration is then reset back to the previous value once the robot has stopped.) If accelerating, the new velocity is incremented by acceleration * dt, where dt is the time elapsed since the last update of the position model in the previous simulation loop iteration: we assume that the next simulation iteration will be within a similar time interval. If decelerating, velocity is decreased. If the desired velicity is within a threshold of the current velocity, then the desired velocity is simply used.</p>
<p>The above process can be logged for debugging by switching the definitions of some macros in the <code>model_position.c</code> source code and recompiling, though note that this will generate a lot of output.</p>
<p>Next, a collision test is performed for the new position of the robot. If any part of the robot shape (including the shapes of any other attached sensor models, such as laser rangefinder) will collide with the environment or any other robot or model, then the robot is not moved to the new position, so motion is effectively stopped immediately. The collision state is indicated to client software via the "stall" flag.</p>
<p>As the robot moves, an updated virtual odometric pose within a global cartesian coordinate frame is also calculated, with error artificially introduced. This is provided to client software as its odometric pose estimate.</p>
<p>Only position, velocity and acceleration of the robot as a whole is simulated. Other aspects of the robot's motion such as momentum or inertia are not simulated, nor are component parts such as wheels, nor the robot's interaction with the world other than collision detection.</p>
<p>The updated pose estimate is calcualed by projecting the robot along its current basic trajectory (velocities) from the previous pose estimate, plus some error. (The pose is initialized to (0,0,0) when the simulated robot is created.)</p>
<pre><code>mx = (vx * dt) * (1 + error.x)
my = (vy * dt) * (1 + error.y)
mth = (vth * dt) * (1 + errror.th)
pose.x += mx * cos(th) - my * sin(th)
pose.y += mx * sin(th) + my * cos(th)
pose.th += mth </code></pre>
<p>vx, vy, vth are the robot's current velocity in its local X and Y axes, and rotational velocity. Th is the robot's current heading (in global pose coordinate frame).<br />
Note that on differential drive robots, vy is always 0 since it cannot directly move along its Y axis, but may be nonzero on robots capable of lateral motion.</p>
<p>In MobileSim 0.6.x, error values of 0.0075 for error.x and error.y and 0.0075 for error.th are used by default for all robots, except for "p3dx_noerr" where no error is used. Starting in MobileSim 0.9.x, there are several choices for calculating error, which can be selected via the --odom-error-mode command-line argument. <code>random_each_update</code> is the default (as was errorneously documented previously.)</p>
<ul>
<li><code>random_init</code> Choose random values within a configured range at startup; each new robot will have different amount of error, even if same type.</li>
<li><code>random_each_update</code> Chose random values within configured range at each simulation iteration.</li>
<li><code>constant</code> Constant values, configured for each robot type.</li>
<li><code>none</code> Use 0 for error values.</li>
</ul>
<p>The error ranges are specified in the robot model definitions (<code>PioneerRobotModels.world.inc</code>) and new custom model definitions may specify error ranges that override defaults. (See Model Definitions below.) The <code>odom_error_range_x</code>, <code>odom_error_range_y</code>, and <code>odom_error_range_a</code> properties specify ranges for error in each axis. Alternatively, an <code>odom_error</code> property can be used for constant error (if <code>constant</code> mode) or for symetric positive/negative error values (random modes) (this is for compatibilty). (Units are meters and radians.) The actual error values being used can be obtained by client software via the SIMSTAT packet (see below).</p>
<p>MobileSim can also calculate a simulated GPS position. This is calculated using the georeference position of the map file, and the simulated robot's position in the map (true position, not pose estimate.) A map must have a georeference point (<code>OriginLatLongAlt</code>) for this to work. The latitude and longitude are provided in the <code>SIMSTAT</code> packet. Some robot models have a GPS receiver position defined, when the corresponding real robot has a standard mounting location for the GPS receiver or antenna. If not, the center of the robot is assumed. Note that ARIA also has a GPS receiver location parameter in its robot parameter files. Some software (such as MOGS) use this to offset GPS positions it receives from both a real GPS and the simulator.</p>
<h4 id="laser-model">laser model</h4>
<p>The laser model represents a simplified scanning rangefinder sensor. The position of the simulated laser in the world is relative to the position of the robot position model and the simulated laser data is updated after the robot has moved.</p>
<p>The code implementing the laser model can be found in the MobileSim source code in <code>stage/src/model_laser.c</code>.</p>
<p>A scanning rangefinder measures distance ranges at fixed degree intervales over its field of view.<br />
At each simulation loop iteration, each of these range values is deterimed by a raycasting algorithm to search the simulation environment at that time. The field of view of the sensor is divided by the number of range samples that wil be taken to determine the angle of each sample. A small amount of static random error is added to each sample's angle, and then for each sample ray, the environment quadtree is searched along until another object is located, or the maximum distance capable is reached. Then the intersaction point between the ray and the shape of that object is calculated, and the distance between the center of the laser rangefinder model and that point is calculated. Finally, a small amount of random error is added to that range value.</p>
<p>A laser may be mounted upside down, in which case the order of readings is reversed.</p>
<p>Objects in the environment may be flagged as invisible to laser sensors, in which case they are ignored.</p>
<p>If the detected object has been configured with a special "reflectance" value, then this is stored with the range value, optionally modified by configurable rules (e.g. distance, angle of incidence, etc.) This simulates the capability of the SICK LMS-200 and some other lasers to differentiate special refelctor material applied to objects.</p>
<p>A range error of +/- 5 mm and angular error of +/- 0.04 degrees is used for simulated LMS-200.<br />
A range error of +/- 7.5mm and angular error of +/- 0.04 degrees is used for LMS-100. A range error of +/- 6mm and agular error of +/- 0.04 degrees is used for S300.</p>
<p>If client software has requested laser data, then at each interval of client communications, the most recently calculated set of laser range data is sent to the client.</p>
<h4 id="ranger-model-used-for-sonar">ranger model (used for sonar)</h4>
<p>The "ranger" model is used to simulate sets of individual, relatively short range distance sensors, such as sonar and IR range sensors. It differs from the "laser" model in that the positions and orientations of each individual sensor transciever can be configured separately.</p>
<p>The code implementing the ranger model can be found in the MobileSim source code in <code>stage/src/model_ranger.c</code>.</p>
<p>In the simplest, default mode, for each configured sensor transciever, a raycasting algorithm is used to search the environment from the center of the sensor's field of view, within the minimum and maximum configured range. This distance is stored as the range data.</p>
<p>In the alternative "closest ray" mode, several raycasts are made within the field of view of the sensor transciever, and the shortest range is used. This mode is not used by default.</p>
<p>Finally, some random error may be added to the range value. +/- 0.5 mm is used, since sonar is generally stable, if not as accurate as the laser in most conditions.</p>
<p>Objects in the environment may be flagged as invisible to laser sensors, in which case they are ignored.</p>
<p>No special timing, acoustic, reflection, or other factors are currently simulated.</p>
<h2 id="advanced-usage">Advanced Usage</h2>
<h4 id="command-line-arguments">Command-line Arguments</h4>
<p>A full listing of MobileSim's command line parameters follows:</p>
<p>Usage: MobileSim [-m <em>map</em>] [-r <em>robot model</em> ...] [...options...]</p>
<table>
<colgroup>
<col width="30%" />
<col width="69%" />
</colgroup>
<tbody>
<tr class="odd">
<td align="left"><code>--map</code> <em>map</em></td>
<td align="left">Load map file (e.g. created with Mapper3)</td>
</tr>
<tr class="even">
<td align="left"><code>-m</code> <em>map</em></td>
<td align="left">Same as <code>-map</code> <em>map</em></td>
</tr>
<tr class="odd">
<td align="left"><code>--nomap</code></td>
<td align="left">Create an "empty" map to start with. Same as <code>-map ""</code>. Ignored if -m is also given.</td>
</tr>
<tr class="even">
<td align="left"><code>--robot</code> <em>model[:name]</em></td>
<td align="left">Create a simulated robot of the given model. If an ARIA robot parameter file is given for <em>model</em>, then MobileSim attempts to load that file from the current working directory, and create an equivalent model definition. May be repeated with different names and models to create multiple simulated robots. Name portion is optional. For example: <code>--robot p3dx --robot amigo:MyRobot -r custom.p:CustomBot</code> See PioneerRobotModels.world.inc for model definitions.</td>
</tr>
<tr class="odd">
<td align="left"><code>-r</code> *model[:name]</td>
<td align="left">Same as <code>--robot</code> <em>model</em><code>or</code>--robot` <em>model:name</em></td>
</tr>
<tr class="even">
<td align="left"><code>--robot-factory</code> <em>model</em></td>
<td align="left">Instead of creating one robot of the given model, accept any number of client programs on its port, creating a new instance of the model for each client, and destroying it when the client disconnects.</td>
</tr>
<tr class="odd">
<td align="left"><code>-R</code> <em>model</em></td>
<td align="left">Same as <code>--robot-factory</code> <em>model</em></td>
</tr>
<tr class="even">
<td align="left"><code>-p</code> <em>port</em></td>
<td align="left">Emulate Pioneer connections starting with TCP port <em>port</em> (Default: 8101)</td>
</tr>
<tr class="odd">
<td align="left"><code>-W</code> <em>worldfile</em></td>
<td align="left">Use Stage worldfile <em>worldfile</em> instead of map, and instead of standard world configuration files.</td>
</tr>
<tr class="even">
<td align="left"><code>--stageworld</code></td>
<td align="left">Same as -W.</td>
</tr>
<tr class="odd">
<td align="left"><code>--fullscreen-gui</code></td>
<td align="left">Display window in fullscreen mode.</td>
</tr>
<tr class="even">
<td align="left"><code>--maximize-gui</code></td>
<td align="left">Display window maximized.</td>
</tr>
<tr class="odd">
<td align="left"><code>--minimize-gui</code></td>
<td align="left">Display window minimized (iconified)</td>
</tr>
<tr class="even">
<td align="left"><code>--noninteractive</code></td>
<td align="left">Don't display any interactive dialog boxes that might block program execution. Also restart MobileSim if it crashes (Linux only).</td>
</tr>
<tr class="odd">
<td align="left"><code>--lite-graphics</code></td>
<td align="left">Disable some graphics for slightly better performance</td>
</tr>
<tr class="even">
<td align="left"><code>--no-graphics</code></td>
<td align="left">Disable all graphics drawing for slightly better performance</td>
</tr>
<tr class="odd">
<td align="left"><code>--html</code></td>
<td align="left">Print log messages and other output in HTML rather than plain text</td>
</tr>
<tr class="even">
<td align="left"><code>--cwd</code> <em>dir</em></td>
<td align="left">Change directory to <em>dir</em> at startup. Client programs can then load maps relative to this directory.</td>
</tr>
<tr class="odd">
<td align="left"><code>--log-file</code> <em>file</em></td>
<td align="left">Print log messages to <em>file</em> instead of standard error console.</td>
</tr>
<tr class="even">
<td align="left"><code>-l</code> <em>file</em></td>
<td align="left">Same as <code>--log-file</code> <em>file</em>.</td>
</tr>
<tr class="odd">
<td align="left"><code>--log-file-max-size</code> <em>size</em></td>
<td align="left">If the amoount of data written to the log file exceeds <em>size</em> bytes, then rotate the log files (up to 5) and open a new log file. This option keeps the total size of all the log files under *size**5 bytes. If --noninteractive is given, the default for <em>size</em> is 5 MB. Otherwise, the default is not to limit the size of the log file at all.</td>
</tr>
<tr class="even">
<td align="left"><code>--update-interval</code> <em>ms</em></td>
<td align="left">Time between each simulation update step. (Default is 100 ms. less may improve simulation performance but impact client responsiveness and data update.)</td>
</tr>
<tr class="odd">
<td align="left"><code>--update-sim-time</code> <em>ms</em></td>
<td align="left">How much simulated time each simulation update takes (Default is equal to update-intenval. More than update-interval results in faster-than-realtime simulation, which may cause problems for clients)</td>
</tr>
<tr class="even">
<td align="left"><code>--start</code> <em>x</em>,<em>y</em>,<em>th</em></td>
<td align="left">Use <em>x</em>, <em>y</em>, <em>th</em> as robot starting point (even if the map has Home objects).</td>
</tr>
<tr class="odd">
<td align="left"><code>--start outside</code></td>
<td align="left">Start robots 2m outside the map bounds -- it later must be moved to within the map bounds to be used.</td>
</tr>
<tr class="even">
<td align="left"><code>--start random</code></td>
<td align="left">Randomly choose a starting place within the map bounds.</td>
</tr>
<tr class="odd">
<td align="left"><code>--resolution</code> <em>r</em></td>
<td align="left">Use resolution <em>r</em> (milimeters) for collisions and sensors. Default is 20mm (2cm)</td>
</tr>
<tr class="even">
<td align="left"><code>--ignore-command</code> <em>num</em></td>
<td align="left">Ignore the command whose number is given. Refer to robot manual and MobileSim documentation for command numbers. For example, to prevent client programs from moving the robot's true position with the <code>SIM_SET_POSE</code> command, number 224, use <code>--ignore-command 224</code>. May be repeated. Warning: MobileSim and/or your program may not function correctly if some critical commands are ignored.</td>
</tr>
<tr class="odd">
<td align="left"><code>--less-verbose</code></td>
<td align="left">Be a bit less verbose about logging messages, especially things that might be frequently logged (such as unsupported commands), to avoid filling up log files with useless info.</td>
</tr>
<tr class="even">
<td align="left"><code>--log-timing-stats</code></td>
<td align="left">Log some simulation timing information every 30 seconds.</td>
</tr>
<tr class="odd">
<td align="left"><code>--bind-to-address</code> <em>address</em></td>
<td align="left">Only listen on the network interface with IP address <em>address</em> for new client connections (default is to listen on all addresses). This lets you run more than one MobileSim process on the same TCP ports on a machine that has more than one network interface.</td>
</tr>
<tr class="even">
<td align="left"><code>--disable-crash-handler</code></td>
<td align="left">Disable the GDB crash handler (and just abort program on fatal signals). No effect on Windows, where there is no crash handler.</td>
</tr>
</tbody>
</table>
<p>Note: Windows' command shell unfortunately does not display the standard console output of GUI programs like MobileSim. To see MobileSim's output, you can either use the <code>--log-file</code> option to log to a file, or run MobileSim from another command shell, such as the <a
href="http://www.mingw.org">MSYS</a> shell (<a href="http://sourceforge.net/project/showfiles.php?group_id=2435&package_id=82721&release_id=158803">download MSYS here</a>).</p>
<h4 id="model-definitions">Model Definitions</h4>
<p>The standard Pioneer robot model definitions are in the file <code>PioneerRobotModels.world.inc</code>, which is installed with MobileSim (by default, in <code>/usr/local/MobileSim</code> on Linux and <code>C:\Program Files\MobileRobots\MobileSim</code> on Windows). This file is used to create the desired robot model when loading a MobileRobots/ActivMedia .map file, and you may include it in your custom Stage worlds as well. It must be present to run MobileSim. To define modified or custom robot model definitions, either modify this file, or create one of these directories:</p>
<ul>
<li><code>~/.MobileSim/include/</code> if on Linux (where ~ is your home directory), or</li>
<li><code>C:\Documents and Settings\*<Your User Name>*\MobileSim\include</code> on Windows XP (Where <em><Your User Name></em> is your user account name.), or</li>
<li><code>C:\Users\*<Your User Name>*\MobileSim\include</code> on Windows 7+ (Where <em><Your User Name></em> is your user account name.), or</li>
</ul>
<p>Any files MobileSim finds in this include directory (except files that begin with a dot ".") are included into the world configuration after PioneerRobotModels.world.inc. (You can also put Stage world and GUI settings, and even model instantiations into these files as well. See the <a href="http://playerstage.sourceforge.net/doc/stage-2.0.0/group__model.html"> Stage documentation </a> for complete documentation of the syntax of these files.) New model definitions from these files can be used with the -r option on the command line using the model definition name, or by typing the name into the Robot Model field of MobileSim's initial dialog box.</p>
<p>When you define a new model, you can change the <code>pioneer_robot_subtype</code> property; this is the robot subtype string that ARIA uses to load client-side parameters for the robot. If you do change this value, you must also create a parameter file (.p file) for that new type in ARIA's 'params' directory.</p>
<p>MobileSim expects common resources like the <code>PioneerRobotModels.world.inc</code> file to be in the standard installation location (<code>/usr/local/MobileSim</code> on Linux; <code>C:\Program Files\MobileRobots\MobileSim</code> on Windows) unless an environment variable named <code>MOBILESIM</code> is set, or on Windows, in the <code>\SOFTWARE\MobileRobots\MobileSim\Install Directory</code> registry key. Change these if you want MobileSim to use resources in a different directory than the standard installation location.</p>
<h5>
Robot speed limits
</h5>
<p>Model definitions for robots ("position" models) have speed limits defined. This is analogous to the limits set in a real robot's firmware.</p>
<h4 id="stage-worldfile-override">Stage Worldfile Override</h4>
<p>Instead of using a map file and the model definitions in <code>PioneerRobotModels.world.inc</code> and the files in <code>~/.MobileSim/include</code>, you may also simply provide a Stage-format world file with the -W or -stageworld command line options. If provided, MobileSim uses only this world file for world configuration, it does not use the common <code>PioneerRobotModels.world.inc</code>, <em>or</em> the files in your "include" directory.</p>
<h4 id="special-simulator-obstacles-objects">Special Simulator Obstacles Objects</h4>
<p>MobileSim includes some "box" model definitions in its model definitions file <code>PioneerRobotModels.world.inc</code>. These are 0.5 x 0.5 meter objects that you can place anywhere in the map, and move with the mouse during the simulation. These boxes are created in the same way as robots, using the <code>-r</code> command line argument. Use the <code>--start</code> option to choose their locations. You can <a href="#modeldefs">create your own model definitions</a> based on the <code>box</code> model type as well (e.g. with different dimensions, color, etc.) MobileSim's predefined <code>box</code> model types are described below:</p>
<dl>
<dt>
<code>box</code>
<dd>
A 0.5 x 0.5 m yellow box that is an obstacle which can also be sensed by laser and sonar.
</dd>
<dt>
<code>box-nolaser</code>
<dd>
A 0.5 x 0.5 m yellow box that is an obstacle which can be sensed by sonar, but <em>not</em> lasers.
</dd>
<dt>
<code>box-nolaser-nosonar</code>
<dd>
A 0.5 x 0.5 m yellow box that is an obstacle which can <em>not</em> be sensed by sonar or lasers (the robot will collide with it and trigger bumpers and stall).
</dd>
<dt>
<code>box-reflector</code>
<dd>
A 0.5 x 0.5 m yellow box that is an obstacle which can be sensed by sonar, and by laser with a high reflectance value (2).
</dd>
</dl>
<p>For example, you can create a simulation with two movable boxes and a Pioneer 3-DX robot with the following command: MobileSim -r p3dx -r box -r box</p>
<p>You can also define custom map object types in a map file, which will allow you to add them to that map file using Mapper3. MobileSim recognizes some additional attributes of the custom types in order to create extra objects in the simulation.</p>
<dl>
<dt>
<code>Sim.Obstacle=</code><em>yes|no</em>
</dt>
<pre><code> <dd>If this attribute is given to a `SectorType`,
then MobileSim creates an extra movable box. (Not supported
yet for `BoundaryType`)
If the value is `yes`, then the object will
be an obstacle that the robot will collide with. If
`no`, then the robot will pass through it.
This attribute controls whether a box is created or not, it</code></pre>
must be given with either a yes or no value.
</dd>
<dt>
<code>Sim.LaserReflect=</code><em>int</em>
</dt>
<pre><code> <dd>If the
*int* value is greater than 1, then it
will be returned to the client with laser readings, if the
laser sensor model is able to detect it according to its
rules for detecting reflectors.
(See `Reflector` below).</dd>
If 1, it will be detected as a normal object by the laser.
If 0, it will not be detected by the laser at all.
</dd></code></pre>
<dt>
<code>Sim.SonarReflect=</code><em>yes|no</em>
</dt>
<pre><code> <dd>If `yes`, then the object will be detected by
sonar. If `no`, then it will not be detected by
sonar.`</dd></code></pre>
</dl>
<dl>
<dt>
<code>Reflector</code>
</dt>
<pre><code> <dd>This creates a line in the map that has a higher
"reflectance" value than the normal LINES data. (Note,
ARIA version 2.5 or later is needed to be able to read the reflectance
value data from the simulater LRF). Both sides of the line
will have high reflectance.</dd></code></pre>
</dl>
<p>To add these custom object type definitions to a map file, first manually edit the map to define a custom type that has a simulator specific attribute. For example, the following defines five object types: * a normal box * a highly reflective box * an box that is invisible to laser and sonar but which the robot will collide with * a box that is invisible to laser and sonar and which the robot will not collide with (it is simply visible in the simulator, this is useful as a simple marker of a place in the map) * a reflector line</p>
<pre><code>MapInfo: SectorType Name=BoxObstacle Label=Sim_BoxObstacle Sim.Obstacle=yes
MapInfo: SectorType Name=ReflectiveBoxObstacle Label=Sim_ReflectiveBoxObstacle Sim.Obstacle=yes Sim.LaserReflect=32
MapInfo: SectorType Name=InvisibleBox Label=Sim_InvisibleBox Shape=Plain Sim.Obstacle=yes Sim.LaserReflect=0 Sim.SonarReflect=no
MapInfo: SectorType Name=MarkerBox Label=Sim_MarkerBox Shape=Plain Sim.Obstacle=no Sim.LaserReflect=0 Sim.SonarReflect=no
MapInfo: BoundaryType Name=Reflector Label=Reflector Desc=Reflector "Color0=0xFF00FF"</code></pre>
<p>You can also add attributes such as <code>Shape</code>, <code>Desc</code>, <code>Color0</code> and <code>Color1</code>. To include spaces in the <code>Desc</code> or <code>Label</code> attributes, surround the whole key=value part in quotes (e.g. <code>"Desc=Invisible Box for Simulator"</code>).</p>
<p>Once these definitions are added to a map file which is then loaded into Mapper3, then Mapper3 makes them available: in the Boundary tools for Reflector lines, and the Sector tools for boxes. You can modify the Color and Shape parameters if you would like them to be displayed differently in Mapper3. When instances of the objects are added with Mapper3 they are then added to the map file as "Cairn" map objects (similar to goals etc.).</p>
<h4 id="special-sectors-in-map-file">Special Sectors in Map File</h4>
<p>MobileSim will recognize certain special sectors if they appear in the map file. Mapper3 does not recognize all of these by default, but if you add the appropriate <code>MapInfo</code> lines to the map with a text editor (see below), they will appear in the "Advanced Areas" menu of Mapper3.</p>
<ul>
<li><code>BadGPSSector</code> and <code>SimBadGPSSector</code>: If a map has a GPS georeference point (<code>OriginLatLongAlt</code>), then MobileSim will provide simulated latitude and longitude in the <code>SIMSTAT</code> packet (see description of <code>SIMSTAT</code> below.)<br />
If the robot is inside a <code>BadGPSSector</code> or <code>SimBadGPSSector</code>, then the value provided in <code>SIMSTAT</code> for the "good GPS" field will be 0. Otherwise it will be 100. <code>ArSimulatedGPS</code> in ARIA will use this to indicate either "NoFix" (if -1), or "SimulatedFix" (if 100) or "BadFix" (0) fix type and ideal (1.0) or bad (0.0) DOP value. MOGS uses <code>BadGPSSector</code> to prevent intermittent or inconsistent GPS positions from reducing navigation quality while in areas that have been marked as "known-bad" areas of GPS coverage.</li>
</ul>
<p>To enable the creation of BadGPSSector and SimBadGPSSector in Mapper3, use a text editor to add the following lines to the map file:</p>
<pre><code>MapInfo: SectorType "Name=BadGPSSector" "Label=BadGPS" "Desc=Area where GPS is known to be unreliable" "Color0=0x888888" "Color1=0xbea4ce"
MapInfo: SectorType "Name=SimBadGPSSector" "Label=SimBadGPS" "Desc=Area where GPS will be made unreliable in MobileSim" "Color0=0x779977" "Color1=0xbea4ce"</code></pre>
<h4 id="default-map-file">Default Map File</h4>
<p>If you find that you are often loading the same map file into MobileSim over and over again, you can save a step by copying that map file into <code>~/.MobileSim</code> (Linux) or <code>\Documents and Settings\*<User Name>*\MobileSim</code> (Windows) and naming it <code>init.map</code>. If this map file exists, MobileSim will load this map at startup if no command-line option is given, rather than dislpaying the initial Load Map File dialog box.</p>
<h4 id="exit-codes">Exit Codes</h4>
<p>The MobileSim process has the following exit codes:</p>
<table>
<tbody>
<tr class="odd">
<td align="center">0</td>
<td align="left">No error</td>
</tr>
<tr class="even">
<td align="center">255 (-1)</td>
<td align="left">Error in command line arguments</td>
</tr>
<tr class="odd">
<td align="center">254 (-2)</td>
<td align="left">Error writing a temporary file on startup</td>
</tr>
<tr class="even">
<td align="center">253 (-3)</td>
<td align="left">Error loading a map file</td>
</tr>
<tr class="odd">
<td align="center">252 (-4)</td>
<td align="left">Error initializing Stage</td>
</tr>
<tr class="even">
<td align="center">250 (-6)</td>
<td align="left">Error loading a robot parameters file (.p file) to define a robot model</td>
</tr>
<tr class="odd">
<td align="center">249 (-7)</td>
<td align="left">Error initializing the Pioneer emulation</td>
</tr>
<tr class="even">
<td align="center">thread</td>
<td align="left"></td>
</tr>
<tr class="odd">
<td align="center">248 (-8)</td>
<td align="left">Error opening a TCP socket for a robot or factory</td>
</tr>
<tr class="even">
<td align="center">236 (-20)</td>
<td align="left">MobileSim crashed, but crash handler caught signal and logged information to log file.</td>
</tr>
</tbody>
</table>
<p>Error codes may also be requested in the <code>SIM_EXIT</code> command by a client (use positive error codes less than 127, to differentiate from possible MobileSim codes).</p>
<h2 id="robot-protocol-support">Robot Protocol Support</h2>
<p>Currently the following parts of the ARCOS/AROS/P2OS/AmigOS/PSOS protocols are supported. This covers all robot motion commands used by ARIA (including both direct motion requests and actions), and several other features.</p>
<table>
<colgroup>
<col width="16%" />
<col width="12%" />
<col width="12%" />
<col width="58%" />
</colgroup>
<thead>
<tr class="header">
<th align="left">Name</th>
<th align="left">Command #</th>
<th align="left">Argument Type</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td align="left">PULSE</td>
<td align="left">0</td>
<td align="left">none</td>
<td align="left">No-op (but reset watchdog timeout)</td>
</tr>
<tr class="even">
<td align="left">OPEN</td>
<td align="left">1</td>
<td align="left">int</td>
<td align="left">Start up standard devices and send SIP packets</td>
</tr>
<tr class="odd">
<td align="left">CLOSE</td>
<td align="left">2</td>
<td align="left">int</td>
<td align="left">Stop standard devices</td>
</tr>
<tr class="even">
<td align="left">ENABLE</td>
<td align="left">4</td>
<td align="left">uint</td>
<td align="left">Enable (1) or disable (0) motors</td>
</tr>
<tr class="odd">
<td align="left">SONAR</td>
<td align="left">28</td>
<td align="left">uint</td>
<td align="left">Disable (0) or re-enable (1) sonar (but using argument bits 1-4 to select particular arrays is not supported)</td>
</tr>
<tr class="even">
<td align="left">CONFIG</td>
<td align="left">18</td>
<td align="left">int</td>
<td align="left">Request a configuration packet</td>
</tr>
<tr class="odd">
<td align="left">STOP</td>
<td align="left">29</td>
<td align="left">int</td>
<td align="left">Stops the robot from moving</td>
</tr>
<tr class="even">
<td align="left">VEL</td>
<td align="left">11</td>
<td align="left">int</td>
<td align="left">Set the translational velocity (mm/sec)</td>
</tr>
<tr class="odd">
<td align="left">ROTATE</td>
<td align="left">9</td>
<td align="left">int</td>
<td align="left">Set rotational velocity, duplicate of RVEL (deg/sec)</td>
</tr>
<tr class="even">
<td align="left">RVEL</td>
<td align="left">21</td>
<td align="left">int</td>
<td align="left">Set rotational velocity, duplicate of ROTATE (deg/sec)</td>
</tr>
<tr class="odd">
<td align="left">VEL2</td>
<td align="left">32</td>
<td align="left">2bytes</td>
<td align="left">Independent wheel velocities. High 8 bits are left wheel velocity, low 8 bits are right wheel velocity.</td>
</tr>
<tr class="even">
<td align="left">HEAD</td>
<td align="left">12</td>
<td align="left">uint</td>
<td align="left">Turn to absolute heading 0-359 (degrees)</td>
</tr>
<tr class="odd">
<td align="left">SETO</td>
<td align="left">7</td>
<td align="left">none</td>
<td align="left">Resets robots odometry back to 0, 0, 0</td>
</tr>
<tr class="even">
<td align="left">DHEAD</td>
<td align="left">13</td>
<td align="left">int</td>
<td align="left">Turn relative to current heading (degrees)</td>
</tr>
<tr class="odd">
<td align="left">SETV</td>
<td align="left">6</td>
<td align="left">int</td>
<td align="left">Sets maximum velocity and MOVE velocity (mm/sec)</td>
</tr>
<tr class="even">
<td align="left">SETRV</td>
<td align="left">10</td>
<td align="left">int</td>
<td align="left">Sets the maximum rotational and HEAD velocity (deg/sec)</td>
</tr>
<tr class="odd">
<td align="left">SETA</td>
<td align="left">5</td>
<td align="left">int</td>
<td align="left">Sets forward translational acceleration or deceleration (mm/sec/sec)</td>
</tr>
<tr class="even">
<td align="left">SETRA</td>
<td align="left">23</td>
<td align="left">int</td>
<td align="left">Sets rotational accel(+) or decel(-) (deg/sec)</td>
</tr>
<tr class="odd">
<td align="left">MOVE</td>
<td align="left">8</td>
<td align="left">int</td>
<td align="left">Translational move (mm)</td>
</tr>
<tr class="even">
<td align="left">LATVEL</td>
<td align="left">110</td>
<td align="left">int</td>
<td align="left">Set lateral velocity (on robots that support it, i.e. Seekur)</td>
</tr>
<tr class="odd">
<td align="left">LATACCEL</td>
<td align="left">113</td>
<td align="left">int</td>
<td align="left">Set lateral acceleration or deceleration (on robots that support it, i.e. Seekur)</td>
</tr>
<tr class="even">
<td align="left">BATTEST</td>
<td align="left">250</td>
<td align="left">int</td>
<td align="left">Artificially set battery voltage, in decivolts (e.g. 105 for 10.5 volts)</td>
</tr>
<tr class="odd">
<td align="left">ESTOP/QSTOP</td>
<td align="left">55</td>
<td align="left">none</td>
<td align="left">Stop with maximum deceleration.</td>
</tr>
<tr class="even">
<td align="left">BUMPSTALL</td>
<td align="left">44</td>
<td align="left">int</td>
<td align="left">Configure bumpstall behavior.</td>
</tr>
<tr class="odd">
<td align="left">TTY2</td>
<td align="left">42</td>
<td align="left">string</td>
<td align="left">Log with string contents</td>
</tr>
<tr class="even">
<td align="left">TTY4</td>
<td align="left">60</td>
<td align="left">string</td>
<td align="left">Log with string contents</td>
</tr>
<tr class="odd">
<td align="left">RESET/MAINT</td>
<td align="left">253/255</td>
<td align="left">none</td>
<td align="left">Abort MobileSim for debugging. If running in noninteractive mode on Linux, restart program after logging some debugging informamtion using gdb.</td>
</tr>
</tbody>
</table>
<h4 id="simulator-only-commands">Simulator-only commands</h4>
<p>For compatability with SRISim and old ARIA versions, equivalent commands with deprecated ID numbers are also accepted, with a warning.</p>
<p>MobileSim will always use the robot name "MobileSim". It will also report an OS version number starting with "S." and the string "SIM" for serial number in the CONFIGpac packet, and respond to the <code>SIM_STAT</code> command with a <code>SIMSTATpac</code> packet and the <code>SIM_CTRL,6</code> command with a <code>SIM_INFO</code> packet. You can use these values in client software to detect whether it is connected to MobileSim or not.</p>
<table>
<colgroup>
<col width="30%" />
<col width="10%" />
<col width="19%" />
<col width="39%" />
</colgroup>
<thead>
<tr class="header">
<th align="left">Name</th>
<th align="left">Command</th>
<th align="left">Argument Type</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td align="left"><code>SIM_SET_POSE</code></td>
<td align="left">224</td>
<td align="left">int4,int4,int4</td>
<td align="left">Move robot to global pose in simulator (does not change odometry). The parameters are 4-byte integers for X, Y and Theta. The packet's argument type byte is ignored. Here is an example of how to send this command in ARIA, where <code>robot</code> is an <code>ArRobot</code> object, and <code>x</code>, <code>y</code> and <code>th</code> are <code>int</code> variables containing desired position in milimeters and degrees: ArRobotPacket pkt; pkt.setID(ArCommands::SIM_SET_POSE); pkt.uByteToBuf(0); // argument type: ignored. pkt.byte4ToBuf(x); pkt.byte4ToBuf(y); pkt.byte4ToBuf(th); pkt.finalizePacket(); robot.getDeviceConnection()->write(pkt.getBuf(), pkt.getLength());</td>
</tr>
<tr class="even">
<td align="left"><code>SIM_RESET</code></td>
<td align="left">225</td>
<td align="left">none</td>
<td align="left">Move robot to original starting position in simulator (e.g. Home point or Dock) and reset odometry to 0,0,0.</td>
</tr>
<tr class="odd">
<td align="left"><code>SIM_LRF_ENABLE</code></td>
<td align="left">230</td>
<td align="left">int</td>
<td align="left">1 to enable simulated laser rangefinder in-band (data packet ID=0x60). 2 to enable simulated LRF with extended information (data packet ID=0x61). 0 to disable LRF. See below for data packet formats.</td>
</tr>
<tr class="even">
<td align="left"><code>SIM_LRF_SET_FOV_START</code></td>
<td align="left">231</td>
<td align="left">int</td>
<td align="left">Set start angle of laser field of view</td>
</tr>
<tr class="odd">
<td align="left"><code>SIM_LRF_SET_FOV_END</code></td>
<td align="left">232</td>
<td align="left">int</td>
<td align="left">Set end angle of laser field of view Currently start and end must be symetrical around 0. ARIA always does this, but if you want configure it differently it won't work.</td>
</tr>
<tr class="even">
<td align="left"><code>SIM_LRF_SET_RES</code></td>
<td align="left">233</td>
<td align="left">int</td>
<td align="left">Set degree increment between each reading; with FOV, this number determines the number of readings in each sweep</td>
</tr>
<tr class="odd">
<td align="left"><code>SIM_CTRL</code></td>
<td align="left">236</td>
<td align="left">int,...</td>
<td align="left">Perform a simulator meta-operation. The initial 2-byte integer indicates the operation. The rest of the packet is operation-specific. See the description below for descriptions of operations.</td>
</tr>
<tr class="even">
<td align="left"><code>SIM_STAT</code></td>
<td align="left">237</td>
<td align="left">none,1,2 or 0</td>
<td align="left">Request SIMSTAT packets (ID=0x62) to be returned. See below. Argument: none or 1 to return one packet, 2 to return a packet before each SIP, or 0 to stop sending.</td>
</tr>
<tr class="odd">
<td align="left"><code>SIM_MESSAGE</code></td>
<td align="left">238</td>
<td align="left">byte,string...</td>
<td align="left">Display the length-prefixed string in the messages window.</td>
</tr>
<tr class="even">
<td align="left"><code>SIM_EXIT</code></td>
<td align="left">239</td>
<td align="left">int</td>
<td align="left">Exit the simulator with the given exit code. Pass a positive integer < 127 as error code, or use 0 to indicate "normal" exit.</td>
</tr>
</tbody>
</table>
<p>The <code>SIM_CTRL</code> command performs miscellaneous simulater meta-operations. The initial 2-byte integer indicates the operation. The rest of the packet is operation-specific.</p>
<table>
<colgroup>
<col width="7%" />
<col width="11%" />
<col width="81%" />
</colgroup>
<thead>
<tr class="header">
<th align="left">Op #</th>
<th align="left">Name</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td align="left">1</td>
<td align="left">Replace map</td>
<td align="left">Remove existing map data and load a new map from the file given as a length-prefixed string folowing the operation code. Note: If the path is not absolute, it will be interpreted as relative to MobileSim's startup working directory, or the directory given with the --cwd command-line argument. For compatibility with Windows and other platforms with case-insensitive file naming, the case of the file name does not matter. A SIM_MAP_CHANGED packet will be sent back to any client when MobileSim is done loading a new map (see below).</td>
</tr>
<tr class="even">
<td align="left">2</td>
<td align="left">Master replace map</td>
<td align="left">Similar to <code>1</code>, but once this command is received, future control commands with operation 1 are ignored, only operation 2 is accepted. Use this when many clients are requesting different maps, but you want one of them (or a seperate program) to instead have control over which map is being used. A SIM_MAP_CHANGED packet will be sent back to any client when MobileSim is done loading a new map (see below).</td>
</tr>
<tr class="odd">
<td align="left">3</td>
<td align="left">Master map clear</td>
<td align="left">Disable master map mode if enabled by <code>2</code></td>
</tr>
<tr class="even">
<td align="left">4</td>
<td align="left">Rotate logs</td>
<td align="left">If logging to a file (--log-file command-line option given), then close current log file, move old log files to backup files (up to 5 are kept), and open a new log file. Only implemented for Linux currently.</td>
</tr>
<tr class="odd">
<td align="left">5</td>
<td align="left">Log detailed state</td>
<td align="left">Log detailed internal simulation state for this robot. (For debugging, mainly.)</td>
</tr>
<tr class="even">
<td align="left">6</td>
<td align="left">Request SIMINFO packet</td>
<td align="left">Request <code>SIMINFO</code> packet (see below).</td>
</tr>
<tr class="odd">
<td align="left">7</td>
<td align="left">Ghost mode</td>
<td align="left">This robot will no longer be visible to other robots' sensors (laser or sonar), and other robots will not collide with it.</td>
</tr>
</tbody>
</table>
<p>The normal simulator laser packet is as follows:</p>
<pre><code>Packet ID ubyte=0x60
Robot X int
Robot Y int
Robot Theta int
Total No. Readings int</code></pre>
<p>Current int, index of the first reading given in this packet Packet Len. int, number of bytes of data that follow For each reading: Reading Range int, Range for reading ...</p>
<p>The extended simulator laser packet is as follows:</p>
<pre><code>Packet ID ubyte=0x61
Total No. Readings int
Current int, Index of first reading given</code></pre>
in this packet Packet Len. int, number of bytes of data that follow
<td colspan="2">
<pre><code>For each reading:
Range int, Range for reading #i
Reflectance ubyte, Reflectance value, if supported
Flags 2 bytes, Reserved
...
Laser Device Index ubyte, Reserved
Flags ubyte, Reserved</code></pre>
<p>The SIMSTAT packet is as follows. New fields may be added in future versions.</p>
<pre><code>Packet ID ubyte=0x62 (98)
unused/reserved NULL byte ubyte=0 reserved/unused
unused/reserved NULL byte ubyte=0 reserved/unused
Flags 4ubyte bit 0=have a map; bit 1=map has origin georeference (OriginLatLonAlt); bit 2=have odometry error data
SimInterval 2ubyte Configured simulated time one loop interval takes
RealInterval 2ubyte Configured real time one loop interval should take
LastInterval 2ubyte Real time the last loop interval was measured at
True X 4byte Robot's "true" X position in the simulator
True Y 4byte Robot's "true" Y position in the simulator
True Z 4byte Robot's "true" Z position in the simulator
True Theta 4byte Robot's "true" rotation on its vertical axis in the simulator
Geo Lat 4byte Robot's latitude (degrees * 10^6). Only valid if map has origin georeference.
Geo Lon 4byte Robot's longitude (degrees * 10^6). Only valid if map has origin georeference.
Geo Alt 4byte Robot's altitude (cm). Only valid if map has origin georeference.
GPS good byte Normally 100. If robot is inside a `BadGPSSector` or `SimBadGPSSector` area, will be 0. If there is no simulated GPS (e.g. map is not georeferenced), will be -1. </code></pre>
<p>Odometry Error X 4byte mm * 10^6. See also Flags field above Odometry Error Y 4byte mm * 10^6. See also Flags field above Odometry Error Th 4byte degrees * 10^6. See also Flags field above</p>
<p>Here is an example of a packet handler function for ARIA that extracts some data from the SIMSTAT packet. Wrap this function in an <code>ArFunctor</code> object and use <code>ArRobot::addPacketHandler()</code> to register it with an <code>ArRobot</code> object.</p>
<pre><code>bool handleSimStatPacket(ArRobotPacket* pkt)
{
if(pkt->getID() != 0x62) return false; // SIMSTAT has id 0x62
printf("SIMSTAT pkt received:\n" );
char a = pkt->bufToByte(); // unused byte
char b = pkt->bufToByte(); // unused byte
ArTypes::UByte4 flags = pkt->bufToUByte4();
printf("\tFlags=0x%x\n", flags);
int simint = pkt->bufToUByte2();
int realint = pkt->bufToUByte2();
int lastint = pkt->bufToUByte2();
printf("\tSimInterval=%d, RealInterval=%d, LastInterval=%d.\n", simint, realint, lastint);
int realX = pkt->bufToByte4();
int realY = pkt->bufToByte4();
int realZ = pkt->bufToByte4();
int realTh = pkt->bufToByte4();
printf("\tTrue Pose = (%d, %d, %d, %d)\n", realX, realY, realZ, realTh);
if(flags & ArUtil::BIT1)
{
double lat = pkt->bufToByte4()/10e6;
double lon = pkt->bufToByte4()/10e6;
double alt = pkt->bufToByte4()/100;
double qual = pkt->bufToByte()/100;
printf("\tLatitude = %f deg., Longitude = %f deg., Altitude = %f m, Quality = %f%%\n", lat, lon, alt, qual);
}
else
{
puts("No geoposition.");
}
return true;
}</code></pre>
<p>When connected to MobileSim and using ArGPSConnector, ARIA will create an ArSimulatedGPS object to read the simulated GPS data.</p>
<p>The <code>SIMINFO</code> packet is as follows. New fields may be added in future versions.</p>
<pre><code>Packet ID ubyte=0x63 (100)
Application name NULL-terminated string Name of simulator
Application version NULL-terminated string Version of simulator
Flags 4ubyte Bit 0=Sim is interactive with user and has a GUI; Bit 1=Sim crashed last time but was automatically restarted.
Num. Devices 4ubyte Number of devices attached to the robot
For each device:
Device Name string Unique name for this device
Device Type string e.g. "laser"
Device Number ubyte To distinguish individual devices of the same type
Device Status ubyte,ubyte,ubyte,ubyte Device-dependent status code(s)
...</code></pre>
<p>The <code>SIM_MAP_CHANGED</code> packet is as follows. This packet is sent to all connected clients if the map is changed or reloaded for any reason. New fields may be added in future versions.</p>
<pre><code>Packet ID ubyte=0x66 (102)
User ubyte. 1=Map was loaded by user command (e.g. via gui), 0=Map was loaded by client program SIM_CTRL command.
Loaded ubyte. 1=A new map was really loaded. 0=Map was not reloaded because already loaded and file is unchanged since last load.
Filename string. filename of map that was loaded.</code></pre>
<h4 id="unsupported-commands">Unsupported commands</h4>
<p>The following commands are not supported, and will be ignored, with a warning message. Some are not applicable to the simulator (ENCODER) or pertain to devices that aren't implemented in the simulator yet (gripper, sounds).</p>
<pre><code>ENCODER 19
POLLING 3
SAY 15
JOYINFO 17
DIGOUT 30
GRIPPER 33
ADSEL 35
GRIPPERVAL 36
GRIPPERPACREQUEST 37
IOREQUEST 40
PTUPOS 41
GETAUX 43
TCM2 45
JOYDRIVE 47
HOSTBAUD 50
AUX1BAUD 51
AUX2BAUD 52
GYRO 58
CALCOMP 65
TTY3 66
GETAUX2 67
SOUND 90
PLAYLIST 91
SOUNDTOG 92
OLD_LOADWORLD 63
OLD_LOADPARAM 61
OLD_STEP 64</code></pre>
<p>The following commands will probably never be supported since they do nothing on modern robots or use is discouraged:</p>
<pre><code>DROTATE 14
DCHEAD 22
KICK 34</code></pre>
<p>These commands are supported for compatability with a previous simulator</p>
<pre><code>OLD_LRF_ENABLE 35 int Start/stop sending laser data in-band
OLD_LRF_PARMSTART 36 int Sets start angle 0-180 degrees; also disables laser; with #37, determines "flipped" order of readings.
OLD_LRF_PARMEND 37 int Sets scan end angle; also disables laser; with #36, determines "flipped" order of readings.
OLD_LRF_PARMINC 38 int Sets inter-sample angle (100ths of degree)</code></pre>
<p>The following commands are normally disabled, but can be re-enabled with the <code>--srisim-compat</code> command-line argument:</p>
<pre><code>OLD_END_SIM 62 none Exit simulator (MobileSim exits completely). Note, this command is also used for another use on real robots and newer version of ARIA send it after connecting (so the simulator exits immediately). You can enable the other SRISim compatability commands with `--srisim-compat`, but disable this command using `--ignore-command 62`
OLD_SETORIGINX 66 int Set the robot's current true X, (Note, conflicts with TTY3 command)
OLD_SETORIGINY 67 int ...Y
OLD_SETORIGINTH 68 int ...Theta
OLD_RESET_TO_ORIGIN 69 none Reset true X Y, TH to 0,0,0</code></pre>
<hr/>
<p>Copyright (C) 2006-2010 MobileRobots Inc.<br> Copyright (C) 2011-2015 Adept Technology<br> Copyright (C) 2016-2017 Adept MobileRobots/Omron Adept Technology All Rights Reserved.</p>
<p>Patrolbot® and Seekur® are registered trademarks of Adept Technology</p>
</body>
</html>