Electronic – Best practice for documenting ports / peripherals

cdocumentationembedded

I've recently taken an interest in embedded development and am wondering how most people document their projects. For example:

Each pin on PORTE is wired to an LED and is aliased as LEDPORT.

Methods related to the LED functionality is located in led.h.

Timer/Counter 0 on PORTC controls the blink rate of the LEDS.

etc.

I can certainly use a bullet list like this while the project is small, but I have a feeling that it will become unwieldy as the project grows into something more complex. How is this typically done? Is there a preferred format for this kind of documentation in the professional embedded development world?

After receiving some feedback, I'm thinking of something like this, does it seem reasonable?

|Port|Pin|Peripheral|Desc
|----|---|----------|----
|E   |0  |Led0      |
|E   |1  |Led1      |
|... |...|...       |
|C   |0  |Timer     |Controls the Led blink rate

Best Answer

The short answer is "whatever makes sense to you and the rest of your team".

Since that isn't very informative as far as how to implement something, ultimately communicating the intended behavior is the point.

Comments can't be tested. They are a risk for becoming outdated and unmaintained in general. Comments can help though with understanding the why. There are other smart engineers like yourself that will figure out the how by reading the actual source.

I would recommend doing some research on writing a Hardware Abstraction Layer (HAL). This does a couple of things.

A HAL will show in one file what pins are being used for what purpose. It might also be advisable to indicate which pins are not used (they come in handy for debug/bringup of new designs, so take the extra two minutes to document unused ports/pins now and save yourself 15 minutes in searching for them when you need them.)
By writing a HAL, the code that uses your HAL (the embedded application) won't care what the actual pinout is. This will ease in portability when (not if) you need to change micros in that the brunt of the work that would have to take place is in the HAL itself and not in your application.

In summary, there's nothing wrong with comments, but the executable code is the only thing that matters in terms of what is actually happening.

Related Solutions

Electronic – What are your best resources for winding custom transformers

As from my experience:

You have to make a form (probably a wooden form) which is exactly the form of the transformer core, but longer.
For convenience make a winding rig - a place to attach the form connected with a handle and a shaft for wire spool. Wire spool has to have some kind of breaking mechanism attached to you get some tension on the wire.
Make a sheet of plywood with a hole exactly the shape of the form - you will use it slide the finished coil from the form.
Wrap a form with a thin cardboard, leave edges of the cardboard so that you can fold them and glue them together after you finish the winding.

The idea is that you attach a form to a handle, put a plywood sheet on it, then put cardboard, then wind the wire, fold cardboard around and use a plywood sheet to pull the coil off the form. Cover the form with soap or paraffin so the coil will slide off more easily.

This is all I have in terms of photos, please excuse the quality and incomprehension.

enter image description here

Electronic – Best practice to keep main() in embedded systems

If you're concerned that code for a simple switch() based state machine (SM) will become untidy, you can split it into smaller subroutines.

void do_state_s1() {
    // stuff
    if ( /* certain  contidition */ ) {
        g_iState = STATE_S2;  // transition to another state
    }
}

void do_state_s2()  {
    // other stuff
    if ( /* some other condition */ ) {
        g_iState = STATE_S1;
    }
}

void do_state_machine() {
    switch (g_iState) {
    case STATE_S1:
        do_state_s1();
        break;

    case STATE_S2:
        do_state_s2();
        break;
    };
}

void main() {
    g_iState = STATE_S1;        // initialize the SM

    while (1) {
        do_state_machine();
    }
}

Best Answer

Related Solutions

Electronic – What are your best resources for winding custom transformers

Electronic – Best practice to keep main() in embedded systems

Related Topic