Servo Trigger Programming Guide

Contributors: Byron J.

Firmware Modifications

Let's take a look at some of the finer points of the Servo Trigger code.

There's a single source file in the project, ServoTrigger.c, and some additional configuration in the Atmel Studio project.

Timing

The range of transit times accessed by the T potentiometer is defined by a table of software values -- the table interprets pot position using an exponential curve, which allows for fine control of very short times on the low end, but still permits a useful longer range at the top. But perhaps these times don't fit your application especially well -- maybe you need extra resolution at the low end, or much longer times at the top end. You can change the timing table to do this.

In the GitHub repository, there is a speadsheet, translation.ods, which calculates the timing tables. Simply type the desired time in seconds into the green cells. The sheet recalculates the timing values, and updates the yellow cells. Cut and paste the yellow cells into the timelut array.

The table is only 17 entries long, which seems rather short -- but keep in mind we're using a microcontroller with only 8KB of flash memory and 512 Bytes of RAM -- we wouldn't want the timing table to fill the whole memory. To increase resolution between the table entries, the firmware performs linear interpolation to create more finely grained points in between.

Modes

The Servo Trigger comes with a couple of response modes that should be useful for most servo control needs, but, in the case they're not a good fit, they can be modified.

The two versions of the product (standard and continuous rotation) are managed with a different build configuration for each version. You can select the build configurations in the toolchain tab of the project settings. If all you're looking to do is transmute a regular Servo Trigger into a Continuous Rotation one (or vice versa), simply select the desired configuration.

The modes are configured by defining symbols that get passed to the compiler. All of the modal variations are present in the same source code, enabled using macros. You can select which modes get loaded by changing the compile-time symbols in the project. In Atmel Studio, select the "Servo Trigger" tab, then navigate to "Toolchain-> AVR/GNU C Compiler->Symbols" item.

The FSMA and FSMB symbols determine which modes are programmed on the Servo Trigger. FSMA defines the unjumpered (default) mode, and FSMB defines the jumpered mode. There are five modes currently defined in the source file.

1. bistableFSM - The default mode - when the input is asserted, it moves from position A to B. While input is held, it will stay at B. When released, it moves back to A.
2. oneshotFSM - Does a complete cycle every time the input is asserted - from A to B, then back to A.
3. ctpFSM- A customization of the oneshotFSM for interactive artist Christopher T Palmer, which allows the B-to-A return cycle to be interrupted by a fresh input actuation.
4. togglingFSM - Each time the input is asserted, it changes from A to B, or B to A. This mode is especially useful for driving continous rotation servos.
5. astableFSM - When the input is asserted, it cycles back and forth between A and B. When the input is inactive, it sits where it was.

You can put any mode in either slot, or even put the same mode in both.

Implementation Details

As you may have guessed from the names, the modes are implemented using Finite State Machines. Finite state machines are a design concept the defines a set of states and a corresponding set of rules that determine how to transition between the states.

Within the Servo Trigger, each mode uses the same basic set of states, which in turn describe how it drives the servo. The states are:

1. Sitting at position A.
2. Moving from A to B.
3. Sitting in position B.
4. Moving from B to A.

The rules that define when the states can change can alter the behavior in significant ways. The different modes of the Servo Trigger are all implemented using the same states but with different transition rules.

FSMs are commonly illustrated using "bubble diagrams," which draw the states as circles and the rules as arrows between the circles. Here's the bubble diagram for the bistable FSM.

Building New State Machines

In the Servo Trigger, a state machine is implemented as a single function, which contains a switch statement wherein each state is a case. At the start of every PWM cycle, the state machine function is called to determine the pulse width and possibly move to new states.

If you want to implement a new state machine, it can be useful to start by drawing the bubble diagram.

If your new FSM is a slight alteration to an existing one, the next best place to look at the existing FSMs -- it might be as simple as transplanting a state transition rule from one function to another. If your FSM is more ambitious, it's still useful to read and understand how the FSM interacts with the rest of the firmware.

Your application may need a subtle variation of an existing FSM or a complete re-formulation. Since the source code is available, you're welcome to modify it to suit your needs!

Starting From Scratch

The Servo Trigger can also be used as an ATTiny84 development board with three trimpots on it for any application you can dream up. Start with an empty project as described in the Getting Started section, and start programming at main()!