EmStar Frequently Asked Question

by The EmStar Team
<emstar-design@cens.ucla.edu>
2005-05-31

Site and Mailing List Search:

New Questions (to be catagorized soon)

Why doesn't my callback function (or timer) seem to get trigged, or is triggered at most once?

Or put another way: What should my callback function return?

DEVICE CLIENTS: You should return EVENT_RENEW if you want it to be called again. Many new users return zero, which unfortunately is equivalent to returning EVENT_DONE.

TIMERS: You should return TIMER_DONE if you want the timer to be reenabled.

DEVICE SERVERS: It depends... See below.

STATUS DEVICE SERVER: status_response_cb_t should return STATUS_MSG_COMPLETE if the response is complete, otherwise, return STATUS_MSG_READABLE to keep the device readable and force a client readback. More info here: http://www.lecs.cs.ucla.edu/lxr/source/emstar/libdev/include/status_dev.h#L61

COMMAND DEVICE SERVER: cmd_dev_cmd_cb_t should return EVENT_RENEW to signal you're ready for the next event. Return EVENT_DONE otherwise. More info here: http://www.lecs.cs.ucla.edu/lxr/source/emstar/libdev/include/command_dev.h#L47

QUERY DEVICE SERVER: query_process_cb_t should return QUERY_DONE if the query response is complete and you're ready for another. QUERY_NO_REPLY if the query is not complete and somethign else will trigger the completion of the transaction. More info here: http://www.lecs.cs.ucla.edu/lxr/source/emstar/libdev/include/query_dev.h#L93

PACKET DEVICE SERVER: pd_send_cb_t should return 0 on success, or 1 if it's blocked. More info here: http://www.lecs.cs.ucla.edu/lxr/source/emstar/libdev/include/packet_dev.h#L79

Why don't various emrun features work for my process? (Shutdown, trapping segfaults, etc.)

In general, you need to call two functions in main (before you call g_main()). Those functions are misc_init(), and emrun_init().

This example is taken from: http://www.lecs.cs.ucla.edu/lxr/source/emstar/devel/block_tree/receiveblock/receiveblock.c#L159 

159 main (int argc, char **argv)
160 {
161   misc_init (&argc, argv, CVSTAG);
162   {                             // EmRun will trigger this callback on shutdown
163     emrun_opts_t emrun_opts = {
164     shutdown:block_generic_shutdown,
165       // shutdown handler
166     data:"receiveblock"        // pointer passed to shutdown handler
167     };
168     emrun_init (&emrun_opts);
169   }
170  ....

EmStar Setup

What platforms run EmStar?

Generally speaking, EmStar will run on any Linux platform. Because EmStar depends on the FUSD kernel module, there is a kernel dependency. Currently, only the 2.4 kernel is officially supported, although the changes required to support 2.6 are not extensive. There may be other minor distribution-specific issues -- if you find any please report them! For embedded systems that are not x86 based, you will need to cross-compile EmStar. EmStar is designed to support cross-compilation, and we provide pre-packaged compilers for the Stargate platform, from our downloads page .

Does EmStar require DevFS?

No. Since release 1.3 EmStar no longer depends on DevFS. This means EmStar should work with standard kernels from RedHat, Debian, etc. DevFS will still provide increased performance, especially during startup for large simulations.

Note: If you are not using DevFS, be sure to run the fusdd daemon before starting EmStar. This daemon is needed by the non-DevFS version of FUSD.

Note: Actually the Debian kernel is compiled with DevFS enabled (but it does not start DevFS at boot). apt-get install devfs, a little bit of configuration and you can take advantage of the increased performance.

Why do I get the error "can't read node id from /etc/id"?

EmStar nodes assume that there is a file /etc/id that tells them their ID. If this file is missing, you will see this error. When you run in simulation mode, EmSim or EmCee will configure the ID for each simulated node, so this error will not occur.

EmStar and Motes

Does EmStar run on Motes?

No, it only runs on Linux platforms.

Can I use EmStar to debug TinyOS/NesC code?

Yes. Using EmTOS you can compile TinyOS applications so that TinyOS runs as a process in EmStar, and thus can participate in EmStar simulations, alongside other simulated Motes or EmStar Microservers.

Can my EmStar application interact with Motes?

Yes. EmStar provides two "link drivers" that provide an EmStar link interface over Mote based MAC layers, the Berkeley MAC and the ISI S-MAC. These drivers enable EmStar applications to send and receive packets over the RF channel, as well as to receive messages sent by "stand-alone Motes". In addition, the EmTOS facility allows a TinyOS VM to run within EmStar, receiving messages from real Motes.

Can I Integrate Mote Code and EmTOS into the EmStar Build?

Yes. You can add EmTOS targets and pure Mote targets to the EmStar build system using a build tos {} block. See the EasyBuld Documentation for more details.

Why Doesn't My EmTOS Stuff Build

There are a number of possibilities... check the Installation Instructions for more details. Also, be sure to enable EmTOS and Mote builds by setting BUILD_EMTOS to 1 in the Make.conf file.

Why do I get a "Mote not responding" error trying to run MoteNIC?

There are several possible causes for this message:

Unfortunately, the current software is not very good at "auto-detecting" so you should make sure that you are using the right combination of EmStar software to match your MAC.

If you're using Berkeley MAC:

If you're using S-MAC:

There are two emrun files in mote/testtabs: motenic.run and smacnic.run that start up the motenic and smacnic software respectively (assuming serial port of ttyS0 and mica2).

Emulation and Simulation

I'm getting a strange parse error trying to start a simulation

The error shown below is caused by running emrun with a simulation config file. You should run emsim instead. 

$ emrun/emrun -t ../link/examples/ping/ping-simconfig 10
Fri Mar 19 19:39:03.183: emrun: ../link/examples/ping/ping-simconfig line 11:
  (at '='): parse error, unexpected '=', expecting '{'
Fri Mar 19 19:39:03.184: *****emrun: configuration failed - 1 error

The error shown below is caused by running emsim with an emrun config file rather than a simulator config file. If you want to run a simulation, you must first create a config file that tells the simulator how many nodes you want to simulate and what software you want them to run. 

$ emrun/emsim ../link/examples/ping/test.run 3
Fri Mar 19 08:00:22.370: emproxy line 2: Number of nodes not specified!

Note

In the repository, files that should be used with emrun end with the .run extension; files that should be used with emsim end with the .sim extension.

The error shown below is due to not having first set a SIM_GROUP environment variable. The simulator allows multiple users on the same machine, by separating them into different simulation "groups". Select a small integer no one else seems to be using, and give a command to your shell like export SIM_GROUP=10. All of your simulation's device files will reside in /dev/sim/groupX/ where X is your group id. 

$ emrun/emsim ../link/examples/ping/test.sim 2
Simulator group ID needs to be set using SIM_GROUP environment variable

The error shown below is due to someone else using the same SIM_GROUP as you. Just pick another value for SIM_GROUP and try again. 

$ emrun/emsim ../link/examples/ping/test.sim 2
Mon Mar 29 12:01:19.716: A group 5 simulation is already running here; pick a different SIM_GROUP

How can I use the "ceiling array" emulation mode?

First, get a simulation running using emsim. Make sure to use one of the Mote channel models so that you get an accurate picture of how much traffic your application sends relative to the channel capacity. Once your simulation works, log into the special ceiling-controller machine and run your simulation again, but using emcee instead of emsim, using exactly the same configuration files. It should, in theory, work seamlessly.

We currently have a tutorial with more detail on using EmCee.

In the LECS/CENS systems lab, gamayun.cs.ucla.edu is our ceiling-array controller, attached to an array of 55 motes. If you're not a member of the lab but would like to use our array to debug software, please contact us on the emstar-users mailing list to arrange access.

How can I build my own ceiling array?

First, there's an investment in hardware and wiring. You need to have N motes attached to an N-port serial multiplexor (or a computer with N serial ports). All the motes need to be wired for power as well. This part can be time-consuming and expensive. Our 55-mote ceiling array cost on the order of $10,000, not including the costs of the motes themselves. This is just the cost of the serial multiplexors, cabling, and our custom serial and daisy-chained power board.

Naim Busek has a page describing details of how to build an array.

Someday, it will be possible to create a wireless distributed array, where each mote plugs into a nearby, networked Linux PC or iPAQ/Stargate. Our FUSDNet feature could be used to import the hostmote devices to a central server. However, this one is on the future work list.

Using the EmStar Build System

Why is the build looping endlessly?

First, try deleting your obj.* directory and re-building from scratch. If the build still loops, check to make sure your computer's clock is set correctly. If you're building using an NFS server, make sure your computer and the NFS server's clock are synchronized with each other using NTP or a similar protocol.

Where should I put my new code in the EmStar tree?

A good place to check experimental software into the main EmStar CVS is the devel directory. devel is not built by the checked-in main BUILD file -- to build code in devel you must uncomment the include that would include it.

If you don't have commit access to the EmStar repository, the best plan may be to maintain your own CVS repository and symlink to it from inside your checked-out EmStar repository. For instance, you might symlink emstar/contrib to my-repo/emstar-contrib. Then, add contrib to the include delcaration in the top-level BUILD file (emstar/BUILD). This gives you revision control over your code and lets you conveniently build it using the EmStar build environment.

If you find yourself maintaining patches to the main EmStar tree that you need for your code to work, please drop us a line! We may be able to save you some trouble by integrate those patches, or similar ones, into the main tree.

How do I build my new program in the EmStar system?

EmStar has a very flexible build system that is responsible for building libraries, services and application executables. This is documented in more detail in the EasyBuild Reference .

To build a new program, first place your source code somewhere in the EmStar tree (See above for advice on where). Then, create a new BUILD file, or add to an existing one. Often it is easiest to start by copying an existing BUILD file, such as the one in skeletons. If your new program files are called test1.c and test2.c in the subdirectory mycode and you want to link them together to create the executable test, the following snippet is more or less what you need: 

build bins {
  local_libs { emrun/emrun, libdev/dev, libmisc/misc, fusd/fusd }

  target test {
    mycode/test1.c,
    mycode/test2.c
  }
}

The directory structure for this example would be: 

emstar/
       contrib/        <-- Assuming this is all inside contrib,
               BUILD   <-- this file contains the snippet above,
               mycode/
                      test1.c  <-- and these are your source files.
                      test2.c
       obj.i686-linux/ <-- And, after you run make...
                      contrib/
                              test  <-- this is your new executable

The Network Stack

What's the difference between an EmStar Node ID and Interface address?

Each node has an identifier, the Node ID, which is simply a unique identifier for the node. This identifier exists regardless of how many or what kind of network interfaces you have. Node ID is either read from the file /etc/id (in a real deployment), or, set to a small integer between 1 and N if you're running an N-node simulation.

In addition, each network interface has an interface address. If the interface is an IP interface (e.g., with UDPd), then the emstar interface address will match the IP address. If you're using other interface types (e.g. the simulator), the interface address is generally a random number, similar to an Ethernet MAC address.

There is no relationship between Node IDs and interface addresses.

How can my program determine its Node ID or interface addresses?

Note: The my_node_id is only set if you first call misc_init(), which performs various emstar-related initialization.