User Tools

Site Tools


newtolab

New To Lab

So you're new to lab? Cool, welcome. Like any new environment, there's a lot of new stuff to learn and it's all probably pretty overwhelming. Unlike jobs or internships you may have had in the past, however, getting started in academic research can be harder. We don't have “New Employee Onboarding”, we don't have an HR department, and your advisor is not your manager.

Communication and Culture

Ubiquitous computing is an interdisciplinary field. However, our lab's main focus to-date has been on the embedded systems side of things. This means that at some point you will most likely be doing board design and fabrication. If you do not have these and other relevant skills (soldering, etc.), it is your responsibility to learn them and to say something if you get stuck.

A major part of grad school is learning when to ask for help, and when to figure things out yourself. On the one hand, success in academia requires being self-motivated and self-reliant. By definition, if you are doing cutting edge research, you are attempting to solve a problem or to answer a question that literally no one else in the world knows the answer to. If you have made it this far, you are probably an independent problem solver, and certainly nothing less will be expected from you as you progress in your career. However, even for independent problem solvers there exist common tasks that often pose difficulties, despite the stupidity of something so common still being so difficult. For a long time, installing a cross-compiler was an excellent example of this. Installing TinyOS is another great example. In embedded systems especially, you're lucky if a thousand people in the world have ever tried to use a given tool, which makes finding external and maintaining internal documentation challenging. In cases like these, help from a colleague can avoid hours of frustration.

That said, the lab is predominately populated with experienced computer engineers, who often assume that everyone else in lab shares their background. If you are missing large parts of a computer engineering or embedded systems background, when asking others in lab for help you need to make explicitly clear what you have tried, what you have figured out, and what you still specifically need help with. This will give the others some insight into where you are mentally and increase the likelihood that you will receive a helpful and complete answer, rather than a vague one that relies on background that you do not have to fill in the details.

There are many tutorials on this wiki for using tools, setting up environments, and even institutional processes like ordering lunch. If you have a question, check the wiki first and see if the answer is there.

Lab Resources

We have a lot of them. And this list (being a list on a wiki that rarely sees updates) will likely be incomplete, but hopefully it serves as a good starting point.

Physical Things

  • Everything on / near the workbenches is community (solder, wire, parts in the grey bins, etc)
  • Tools: We have many of them, mostly on / near the workbenches, but there are exceptions. If you need something, ask around, people should know. If we don't have a tool you need, we either have access to one (e.g. laser cutter) or we should probably buy it.
  • If we're running low on something buy more – if you don't know how, ask.
  • If you need a new laptop / desktop / whatever – ask.
  • Spare Parts
    • We have kits for most basic things (resistors, caps, diodes, LEDs, etc)
    • Many common IC's (e.g. FTDI's, or a MAX1555 (battery charger)) have spares from previous projects. If you need something, ask around.
  • The AV Setup
    • We have a projector and speakers in lab. Everything runs through the Denon AV Receiver in the corner by the door.
    • We usually use Apple's AirPlay, through the AppleTV if you'd like to get video working, and often through the Denon directly if you're just doing audio (it has native support for that).
    • We've had a dedicated media PC from time-to-time, and that's nice when it's around, but it often gets co-opted for other purposes. Don't take the absence of a media PC as meaning that you can't use the AV setup.
    • It is a shared resource, so be mindful that; we try to play music amenable to everyone who's around, but if we fail, yell at us.
    • The surround sound is usually an after-hours / weekend thing, it can certainly be heard in the labs next door, so we generally don't use it before 5PM.

Digital Things

  • Accounts
    • This wiki: energy.eecs.umich.edu
      • Like any good wiki, it's mostly an amalgamation of useful and dated information. At some point, you should go through all the links from the home page. It'll probably take you an hour to read/skim through all of it and will give you an impression of what's here.
      • Getting access: e-mail Pat with your desired login name
    • github.com/lab11
      • Most of our projects are hosted here. “lab11” is our github organization.
      • Getting access: create a github account if you don't have one. E-mail anyone to add you (though probably Pat, you can do all of these in one big e-mail to him).
    • shed: energy.eecs.umich.edu
      • shed is our lab's svn server. It is mostly used for papers, as of October 2013:
        ~/shed/ $ tree -L 1
        .
        |-- classes                 Materials for courses we've worked on. Mostly a convenient repository that was already set up.
        |-- eagle                   Useful tools for using EagleCAD (see further below). **Not** projects.
        |-- externals               Legacy. Do not use.
        |-- funding                 All of the fellowship applications anyone from our lab has submitted. Good resource for finding fellowships to apply for, seeing example essays, and reviews.
        |-- generally_useful        Some random things that don't fit the other categories. Notes from meetings are tracked here.
        |-- papers                  All of the papers our lab has written.
        |   |-- create_paper_tup.sh Use this script to create a new paper.
        |-- projects                Older projects from our lab before migrating to github. Some things in here are still used.
        |-- scripts                 Some useful scripts for making life easier. It is recommended to add this to your path (e.g. in your .bashrc, PATH="$PATH:~/shed/scripts")
        |-- sdr                     The uSDR project. This should probably be moved.
        `-- tinyos                  Legacy. Do not use.
      • Getting access: e-mail Pat your ssh public key and a preferred user name. Then svn co svn+ssh://energy.eecs.umich.edu/svnroot/shed
    • shed-media: nuclear.eecs.umich.edu
      • A svn repo for images and videos relevant to our lab. These are often raw images from good cameras. The whole repo is ~58GB as of December 2014. I wouldn't try checking it out on a plane.
      • Getting access: e-mail Pat your ssh public key and a preferred user name. Then svn co svn+ssh://nuclear.eecs.umich.edu/svn/shed-media
    • shed-data: nuclear.eecs.umich.edu
      • An svn repo for data from projects. Rumor has it that this repo was 40 GB in December 2014. Maybe do this one from ethernet…
      • Getting access: e-mail Pat your ssh public key and a preferred user name. Then svn co svn+ssh://nuclear.eecs.umich.edu/svn/shed-data
    • mweiser: groups.google.com
      • For historical reasons, our group e-mail list is a google group, not a umich one. It is mweiser@groups.google.com
      • This list also includes all our lab alumni. They occasionally chime in with interesting points on conversations. It is not a high volume list.
      • Getting access: e-mail Pat your preferred e-mail account for sending / receiving e-mail
    • mweiser-active: groups.google.com
      • This is a subset of mwesier. It has only the people who are physically in Ann Arbor. It's purpose is to make inviting the lab to calendar events easier. It shouldn't really be used for anything else.
  • Software
  • Tools
    • We are an OS-agnostic shop. The reality of embedded systems is that often to successfully use a random tool requires that you replicate the setup of that one dude who wrote the programmer in his garage one night. We all have Windows and Linux and most of us own Macs. You need to be comfortable in all ecosystems. If you aren't yet, start.
    • Coding Ecosystem
      • Use version control. Use the lab11 github. If you don't know git, now is the time to learn.
      • You'll need a cross-compiler eventually. This isn't so hard nowadays, Prabal has a decent write-up if you're stuck.
      • We prefer tup over make. All of our papers are built using tup (why? we could never successfully express dependencies using make. Using tup has been much easier and more reliable). Most of us use tup for our software projects as well, our guess is that once you get used to it you'll never want to go back.
      • vim is the one true editor to rule them all, unless you like sublime (ask Will for a license), or you're Prabal and were raised a heathen (read: emacs user), or whatever really. I mean seriously, if it puts bits in files we're cool with it.
      • Coding Style: Internally consistent. For a given project, be consistent. If you work on someone else's stuff, adapt. Bonus points for including meta-data in files to enforce it, many tools will parse vim modelines correctly, they're kind of a pseudo-standard.
    • Paper Ecosystem
      • We write our papers in Latex. This is expected of quality academic publications. You must learn Latex. Latex is simple-ish on the surface (basic documents are easy), but gets complicated / ugly quickly (anything beyond basic text on a page can be.. complicated).
      • Install the texlive-full package. Yes, it's ~2GB but it's really not worth the effort of installing individual packages manually.
      • We have a pretty good corpus of examples in the shed/papers directory.
      • If you're starting a new paper, use the “create_paper” script in shed/papers. It will put things in the right format and give you a nice skeleton.
      • If you find yourself fighting Latex, ask for help. It's errors are notoriously bad, eventually you'll learn them (mostly..), but no one has expectations at first.
      • Missing those red squiggles? It's been shown to be a good thing to not have them while you're generating text (distracts from flow / train of thought / etc if you're distracted by spelling). At the same time publishing a paper full of spelling errors is embarrassing for all involved. Try aspell -c intro.tex (or w/e), it will fix your problems.
      • Figures
        • We have a lot of opinions on how to generate good figures. This is highly subjective, but we think our opinions are pretty good. When you're getting started with this, set up some time to talk figures with someone.
      • Images
        • If you have some static content (e.g. picture of an experimental setup, block diagram), those go in the images folder, not figs.
        • Latex can be annoying w.r.t. file formats and things. Our build system will automatically create all of the required files.
        • When including graphics in latex, do not use the file extension.
        • Putting this all together: To include mysetup.jpg, put that picture in the images/ folder. In Latex simply use \includegraphics[width=\columnwidth]{mysetup}.
        • As a last detail, if you're including pictures, you shouldn't use the raw image from a high-quality camera. Resize it to something reasonable (500~1000px width usually is a good compromise of quality / size). Most conferences have limits on the final file size of your paper.

Lab Conventions

Habits we've formed over time that have proven to be a good idea, loosely organized.

Project and Part Organization

Physical

All of our projects live in project boxes. A project box contains all the extra boards, extra parts, working boards, documentation, etc to build a project. Project boxes are sorted alphabetically and live on the back storage shelf. Don't take things from other people's projects without asking. If you need a project box, ask.

All of the parts for your project should live in your project box. Digikey (and other supplies) ships you each part in well-sized bag. Keep this bag. Digikey staples labels to the bags, these have been known to fall off. The label is a sticker, however. When you get parts, stick the label to the bag itself.

Digital

We (loosely) have a repository per-project. All repositories are part of our github organization (github.com/lab11). Do not put things in Dropbox. Do not just keep things on your local machine. Learn how to use version control and use it.

Project Layout

For the most part, this is whatever you'd like. The only exception is when building boards. We have some conventions that you have to follow for all of the scripts to work.

  • Put everything related to the PCB in a hardware directory
  • Every unique board should have its own directory
  • Every revision of that board should be a subdirectory of the board directory (even the first one).
  • We name revisions rev_a, rev_b, etc, not 1, 2, 3.

The following layout is an example of one project, with several boards–some with multiple revisions–, some supporting software, and other information:

[bash] Sun 27 Oct 19:22 [ppannuto:pfet-v2[master] ~/code/lab11/gecko]
$ tree -d .
.
|-- contiki
|   |-- apps
|   |   |-- adctest
|   |   |-- framtest
|   |   |-- SEHmonjolo
|   |   |-- SEHpacket
|   |   `-- spitest
|   `-- platform
|       `-- sehnsor
|           `-- dev
|-- hardware
|   |-- datasheets
|   |-- gecko
|   |   |-- rev_a
|   |   |-- rev_b
|   |   `-- rev_c
|   |-- gecko_power_supply
|   |   |-- rev_a
|   |   |-- rev_b
|   |   |-- rev_c
|   |   |-- rev_d
|   |   `-- rev_e
|   |-- impulse
|   |   |-- rev_a
|   |   |-- rev_b
|   |   `-- rev_c
|   |-- sEHnsor
|   |   `-- rev_a
|   `-- solar_panel_mount
|       |-- rev_a
|       `-- rev_b
`-- media
  • As a last detail: The board and schematic should be named the same as the directory. The BOM should be named project_bom.xls[x]:

An example from the above project would be:

[bash] Sun 27 Oct 21:18 [ppannuto:pfet-v2[master] ~/code/lab11/gecko/hardware/gecko/rev_c]
$ tree .
.
|-- gecko_bom.xls
|-- gecko.brd
`-- gecko.sch

Eagle

EagleCAD is… okay software. It has a few properties that are nice:

  • It's “free” (for 2-layer boards.. under a certain size)
  • It's relatively cheap if you do have to buy it, especially for students and especially compared to the alternative (Altium).

This matters. One of the more fundamental tenets of science is the reproducibility of experimental results. Frustratingly, academic experiments are notoriously hard to replicate. We try to do better than our peers in this regard. This is the reason that all of our work goes into a repository and why that repository is available to the public. Initially, the availability of Eagle was a motivation for choosing it. The reality is that people have the CAD software they have. Our reasons for sticking with it now are mostly that we have a reasonable corpus of experience with it and it's cross-platform.

The rest of this section is not seeking to be an Eagle tutorial, there are plenty of those online (Sparkfun's is pretty good) or the SPLAB/MESH/Hub offers lessons.

Designing Your Circuit

Eagle is not a tool for “thinking” out a circuit. It is for capturing a final design and producing it. Fundamentally, it is a CAD tool, it is not a circuit design tool. The brainstorming / design / etc stage should be done on pen and paper, or whiteboard, or something like SPICE if you need to actually model circuits. This means that by the time you're opening Eagle, you already know what your schematic is going to look like, because…

Building Parts (Libraries)

In order to create a schematic, you have to have parts to place on the schematic. While Eagle has built in basics (resistors, caps, etc), they do not have parts for every IC ever conceived 1). While there are some crowdsourced part libraries online, the unfortunate reality is that the crowd is pretty bad at making parts well, or even making them correctly. Once you start getting comfortable making your own parts, this will really be a pretty quick part of the process, but to some degree it will always be a little annoying.

When you make a new part, in the Package editor (the last step where you connected pins to pads), there is an option at the bottom of the screen to add Attributes to you part. For every part you make, add an attribute indicating the supplier and the supplier part number (e.g. name = “DIGIKEY” and value = “ND-101”). This is the supplier, not the manufacturer. This will make your life easier when you generate a bill of materials (BOM).

We have a small library of parts we use often in shed/eagle/lbr. You can “trust” these parts. We've used them on boards and they have been proven to work. We also have a copy of the sparkfun part library here. These parts tend to be usually good, but you should give them a once over.

Drawing Your Schematic

Schematics should be clean and well organized. A new Eagle file is completely blank. Start by adding a frame from our shed/eagle/lbr/frames.lbr. This frame will ensure relevant information ends up on your schematic (your name, board name, page numbers, etc). Next you should add a Block M from shed/eagle/lbr/logos.lbr. Branding is important, it helps associate our work and is good for promoting you as a researcher. For the same reason, your name should be on the board when you're done. Don't forget to fill in your name on the frame part.

Draw your schematic in a way that is useful, such that someone unfamiliar with your design could glance over an figure out. Learn what named nets are and use them—you shouldn't need to cross wires on a schematic.

Designing Your Board

Your board doesn't need to be 4 layers, 2 is enough. If your first board is a 4 layer board, it's probably going to be too complicated to get right.

Ask someone about these things if you don't know what they mean:

  • Use planes.
  • Lay out big parts first.
  • Move things until airwires look like they aren't crossing much.
  • Tent your vias
  • Add stitching vias

Finishing Your Design

Use the smash command liberally. Move labels around so they are somewhere useful. Values aren't that useful in practice, they're just noise.

Make sure all your silkscreen is vector font, 12%, and at least .004, .003 if you really must but readability will suffer.

Put your name on the board. Make sure there is a Block M on the board. Put the date on the board. Put the revision on the board.

Ordering The Boards

Once you're ready to go, use the eagle.py script (located in github.com/lab11/eagle/scripts). This creates a nice zip file you can upload to the board house with everything you need.

Check this file into version control. Yes, on the surface this violates the “don't check in built files” rule of version control. In this case, however, you are checking in files that should never change. These files capture the state of exactly what you built. If you want to build more copies of this board, you should use exactly these files, you should not recreate them. If you need to change something (even something tiny, “one little airwire I missed”), then you create a new revision. This is non-negotiable. A shipped board is a golden master. It is unchangeable.

We primarily order from Sunstone, we also use Advanced Circuits from time to time. If you're ordering from Sunstone, we have a collection of the coupons they send us available here. You can only use one per order, but you can use it on multiple orders (they seem to time out every couple months or so). The free expedite coupons are the most useful.

Other Wiki Entries On Eagle

We should consolidate this information someday. Until then:

1) Although, as an aside: If any manufacturer ever made Eagle parts available for their chips, I would use them exclusively. I think it is unbelievably stupid that thousands of engineers are re-creating Eagle parts for every chip they use.
newtolab.txt · Last modified: 2015/10/21 18:17 by bradjc