1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>AltOS</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" title="AltOS"><div class="titlepage"><div><div><h1 class="title"><a name="idm14563456"></a>AltOS</h1></div><div><h2 class="subtitle">Altos Metrum Operating System</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Keith</span> <span class="surname">Packard</span></h3></div></div><div><p class="copyright">Copyright © 2010 Keith Packard</p></div><div><div class="legalnotice" title="Legal Notice"><a name="idp1614752"></a><p>
2 This document is released under the terms of the
3 <a class="ulink" href="http://creativecommons.org/licenses/by-sa/3.0/" target="_top">
4 Creative Commons ShareAlike 3.0
7 </p></div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr><tr><td align="left">Revision 0.1</td><td align="left">22 November 2010</td></tr><tr><td align="left" colspan="2">Initial content</td></tr></table></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#idp2682856">1. Overview</a></span></dt><dt><span class="chapter"><a href="#idp2398120">2. Programming the 8051 with SDCC</a></span></dt><dd><dl><dt><span class="section"><a href="#idp898968">1. 8051 memory spaces</a></span></dt><dd><dl><dt><span class="section"><a href="#idp2023952">1.1. __data</a></span></dt><dt><span class="section"><a href="#idp3558352">1.2. __idata</a></span></dt><dt><span class="section"><a href="#idp2842744">1.3. __xdata</a></span></dt><dt><span class="section"><a href="#idp2384616">1.4. __pdata</a></span></dt><dt><span class="section"><a href="#idp2387640">1.5. __code</a></span></dt><dt><span class="section"><a href="#idp2712072">1.6. __bit</a></span></dt><dt><span class="section"><a href="#idp2470984">1.7. __sfr, __sfr16, __sfr32, __sbit</a></span></dt></dl></dd><dt><span class="section"><a href="#idp3567856">2. Function calls on the 8051</a></span></dt><dd><dl><dt><span class="section"><a href="#idp3012760">2.1. __reentrant functions</a></span></dt><dt><span class="section"><a href="#idp3274328">2.2. Non __reentrant functions</a></span></dt><dt><span class="section"><a href="#idp1868232">2.3. __interrupt functions</a></span></dt><dt><span class="section"><a href="#idp2323224">2.4. __critical functions and statements</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#idp2522240">3. Task functions</a></span></dt><dd><dl><dt><span class="section"><a href="#idp1968112">1. ao_add_task</a></span></dt><dt><span class="section"><a href="#idp3359576">2. ao_exit</a></span></dt><dt><span class="section"><a href="#idp3085968">3. ao_sleep</a></span></dt><dt><span class="section"><a href="#idp3004432">4. ao_wakeup</a></span></dt><dt><span class="section"><a href="#idp2423736">5. ao_alarm</a></span></dt><dt><span class="section"><a href="#idp2605456">6. ao_start_scheduler</a></span></dt><dt><span class="section"><a href="#idp3312896">7. ao_clock_init</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp2103648">4. Timer Functions</a></span></dt><dd><dl><dt><span class="section"><a href="#idp2407008">1. ao_time</a></span></dt><dt><span class="section"><a href="#idp2512832">2. ao_delay</a></span></dt><dt><span class="section"><a href="#idp2252856">3. ao_timer_set_adc_interval</a></span></dt><dt><span class="section"><a href="#idp3005352">4. ao_timer_init</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp3256712">5. AltOS Mutexes</a></span></dt><dd><dl><dt><span class="section"><a href="#idp2419784">1. ao_mutex_get</a></span></dt><dt><span class="section"><a href="#idp3558880">2. ao_mutex_put</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp1927912">6. CC1111 DMA engine</a></span></dt><dd><dl><dt><span class="section"><a href="#idp3033536">1. ao_dma_alloc</a></span></dt><dt><span class="section"><a href="#idp3322920">2. ao_dma_set_transfer</a></span></dt><dt><span class="section"><a href="#idp2415360">3. ao_dma_start</a></span></dt><dt><span class="section"><a href="#idp2383728">4. ao_dma_trigger</a></span></dt><dt><span class="section"><a href="#idp1636944">5. ao_dma_abort</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp3215304">7. SDCC Stdio interface</a></span></dt><dd><dl><dt><span class="section"><a href="#idp2502672">1. putchar</a></span></dt><dt><span class="section"><a href="#idp2459944">2. getchar</a></span></dt><dt><span class="section"><a href="#idp2914760">3. flush</a></span></dt><dt><span class="section"><a href="#idp2873064">4. ao_add_stdio</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp2170912">8. Command line interface</a></span></dt><dd><dl><dt><span class="section"><a href="#idp3529992">1. ao_cmd_register</a></span></dt><dt><span class="section"><a href="#idp2645232">2. ao_cmd_lex</a></span></dt><dt><span class="section"><a href="#idp2564824">3. ao_cmd_put16</a></span></dt><dt><span class="section"><a href="#idp3113528">4. ao_cmd_put8</a></span></dt><dt><span class="section"><a href="#idp1935488">5. ao_cmd_white</a></span></dt><dt><span class="section"><a href="#idp1896024">6. ao_cmd_hex</a></span></dt><dt><span class="section"><a href="#idp2433952">7. ao_cmd_decimal</a></span></dt><dt><span class="section"><a href="#idp2883960">8. ao_match_word</a></span></dt><dt><span class="section"><a href="#idp3489544">9. ao_cmd_init</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp2151344">9. CC1111 USB target device</a></span></dt><dd><dl><dt><span class="section"><a href="#idp2038816">1. ao_usb_flush</a></span></dt><dt><span class="section"><a href="#idp2901984">2. ao_usb_putchar</a></span></dt><dt><span class="section"><a href="#idp1930120">3. ao_usb_pollchar</a></span></dt><dt><span class="section"><a href="#idp2176008">4. ao_usb_getchar</a></span></dt><dt><span class="section"><a href="#idp1694928">5. ao_usb_disable</a></span></dt><dt><span class="section"><a href="#idp2859448">6. ao_usb_enable</a></span></dt><dt><span class="section"><a href="#idp2323496">7. ao_usb_init</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp3103048">10. CC1111 Serial peripheral</a></span></dt><dd><dl><dt><span class="section"><a href="#idp864464">1. ao_serial_getchar</a></span></dt><dt><span class="section"><a href="#idp2883824">2. ao_serial_putchar</a></span></dt><dt><span class="section"><a href="#idp1519672">3. ao_serial_drain</a></span></dt><dt><span class="section"><a href="#idp2341432">4. ao_serial_set_speed</a></span></dt><dt><span class="section"><a href="#idp1472312">5. ao_serial_init</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp1597944">11. CC1111 Radio peripheral</a></span></dt><dd><dl><dt><span class="section"><a href="#idp2842880">1. ao_radio_set_telemetry</a></span></dt><dt><span class="section"><a href="#idp2488848">2. ao_radio_set_packet</a></span></dt><dt><span class="section"><a href="#idp3223464">3. ao_radio_set_rdf</a></span></dt><dt><span class="section"><a href="#idp3006000">4. ao_radio_idle</a></span></dt><dt><span class="section"><a href="#idp2577544">5. ao_radio_get</a></span></dt><dt><span class="section"><a href="#idp2990720">6. ao_radio_put</a></span></dt><dt><span class="section"><a href="#idp2892440">7. ao_radio_abort</a></span></dt><dt><span class="section"><a href="#idp2871216">8. ao_radio_send</a></span></dt><dt><span class="section"><a href="#idp2464440">9. ao_radio_recv</a></span></dt><dt><span class="section"><a href="#idp2485328">10. ao_radio_rdf</a></span></dt><dt><span class="section"><a href="#idp2075376">11. ao_packet_putchar</a></span></dt><dt><span class="section"><a href="#idp2237088">12. ao_packet_pollchar</a></span></dt><dt><span class="section"><a href="#idp2384480">13. ao_packet_slave_start</a></span></dt><dt><span class="section"><a href="#idp2780480">14. ao_packet_slave_stop</a></span></dt><dt><span class="section"><a href="#idp2387432">15. ao_packet_slave_init</a></span></dt><dt><span class="section"><a href="#idp2526032">16. ao_packet_master_init</a></span></dt></dl></dd></dl></div><div class="chapter" title="Chapter 1. Overview"><div class="titlepage"><div><div><h2 class="title"><a name="idp2682856"></a>Chapter 1. Overview</h2></div></div></div><p>
8 AltOS is a operating system built for the 8051-compatible
9 processor found in the TI cc1111 microcontroller. It's designed
10 to be small and easy to program with. The main features are:
11 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Multi-tasking. While the 8051 doesn't provide separate
12 address spaces, it's often easier to write code that operates
13 in separate threads instead of tying everything into one giant
15 </p></li><li class="listitem"><p>Non-preemptive. This increases latency for thread
16 switching but reduces the number of places where context
17 switching can occur. It also simplifies the operating system
18 design somewhat. Nothing in the target system (rocket flight
19 control) has tight timing requirements, and so this seems like
20 a reasonable compromise.
21 </p></li><li class="listitem"><p>Sleep/wakeup scheduling. Taken directly from ancient
22 Unix designs, these two provide the fundemental scheduling
23 primitive within AltOS.
24 </p></li><li class="listitem"><p>Mutexes. As a locking primitive, mutexes are easier to
25 use than semaphores, at least in my experience.
26 </p></li><li class="listitem"><p>Timers. Tasks can set an alarm which will abort any
27 pending sleep, allowing operations to time-out instead of
29 </p></li></ul></div><p>
31 The device drivers and other subsystems in AltOS are
32 conventionally enabled by invoking their _init() function from
33 the 'main' function before that calls
34 ao_start_scheduler(). These functions initialize the pin
35 assignments, add various commands to the command processor and
36 may add tasks to the scheduler to handle the device. A typical
37 main program, thus, looks like:
38 </p><pre class="programlisting">
44 /* Turn on the LED until the system is stable */
45 ao_led_init(LEDS_AVAILABLE);
46 ao_led_on(AO_LED_RED);
50 ao_monitor_init(AO_LED_GREEN, TRUE);
51 ao_rssi_init(AO_LED_RED);
53 ao_packet_slave_init();
54 ao_packet_master_init();
62 As you can see, a long sequence of subsystems are initialized
63 and then the scheduler is started.
64 </p></div><div class="chapter" title="Chapter 2. Programming the 8051 with SDCC"><div class="titlepage"><div><div><h2 class="title"><a name="idp2398120"></a>Chapter 2. Programming the 8051 with SDCC</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#idp898968">1. 8051 memory spaces</a></span></dt><dd><dl><dt><span class="section"><a href="#idp2023952">1.1. __data</a></span></dt><dt><span class="section"><a href="#idp3558352">1.2. __idata</a></span></dt><dt><span class="section"><a href="#idp2842744">1.3. __xdata</a></span></dt><dt><span class="section"><a href="#idp2384616">1.4. __pdata</a></span></dt><dt><span class="section"><a href="#idp2387640">1.5. __code</a></span></dt><dt><span class="section"><a href="#idp2712072">1.6. __bit</a></span></dt><dt><span class="section"><a href="#idp2470984">1.7. __sfr, __sfr16, __sfr32, __sbit</a></span></dt></dl></dd><dt><span class="section"><a href="#idp3567856">2. Function calls on the 8051</a></span></dt><dd><dl><dt><span class="section"><a href="#idp3012760">2.1. __reentrant functions</a></span></dt><dt><span class="section"><a href="#idp3274328">2.2. Non __reentrant functions</a></span></dt><dt><span class="section"><a href="#idp1868232">2.3. __interrupt functions</a></span></dt><dt><span class="section"><a href="#idp2323224">2.4. __critical functions and statements</a></span></dt></dl></dd></dl></div><p>
65 The 8051 is a primitive 8-bit processor, designed in the mists
66 of time in as few transistors as possible. The architecture is
67 highly irregular and includes several separate memory
68 spaces. Furthermore, accessing stack variables is slow, and the
69 stack itself is of limited size. While SDCC papers over the
70 instruction set, it is not completely able to hide the memory
71 architecture from the application designer.
72 </p><div class="section" title="1. 8051 memory spaces"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp898968"></a>1. 8051 memory spaces</h2></div></div></div><p>
73 The __data/__xdata/__code memory spaces below were completely
74 separate in the original 8051 design. In the cc1111, this
75 isn't true—they all live in a single unified 64kB address
76 space, and so it's possible to convert any address into a
77 unique 16-bit address. SDCC doesn't know this, and so a
78 'global' address to SDCC consumes 3 bytes of memory, 1 byte as
79 a tag indicating the memory space and 2 bytes of offset within
80 that space. AltOS avoids these 3-byte addresses as much as
81 possible; using them involves a function call per byte
82 access. The result is that nearly every variable declaration
83 is decorated with a memory space identifier which clutters the
84 code but makes the resulting code far smaller and more
86 </p><div class="section" title="1.1. __data"><div class="titlepage"><div><div><h3 class="title"><a name="idp2023952"></a>1.1. __data</h3></div></div></div><p>
87 The 8051 can directly address these 128 bytes of
88 memory. This makes them precious so they should be
89 reserved for frequently addressed values. Oh, just to
90 confuse things further, the 8 general registers in the
91 CPU are actually stored in this memory space. There are
92 magic instructions to 'bank switch' among 4 banks of
93 these registers located at 0x00 - 0x1F. AltOS uses only
94 the first bank at 0x00 - 0x07, leaving the other 24
95 bytes available for other data.
96 </p></div><div class="section" title="1.2. __idata"><div class="titlepage"><div><div><h3 class="title"><a name="idp3558352"></a>1.2. __idata</h3></div></div></div><p>
97 There are an additional 128 bytes of internal memory
98 that share the same address space as __data but which
99 cannot be directly addressed. The stack normally
100 occupies this space and so AltOS doesn't place any
102 </p></div><div class="section" title="1.3. __xdata"><div class="titlepage"><div><div><h3 class="title"><a name="idp2842744"></a>1.3. __xdata</h3></div></div></div><p>
103 This is additional general memory accessed through a
104 single 16-bit address register. The CC1111F32 has 32kB
105 of memory available here. Most program data should live
106 in this memory space.
107 </p></div><div class="section" title="1.4. __pdata"><div class="titlepage"><div><div><h3 class="title"><a name="idp2384616"></a>1.4. __pdata</h3></div></div></div><p>
108 This is an alias for the first 256 bytes of __xdata
109 memory, but uses a shorter addressing mode with
110 single global 8-bit value for the high 8 bits of the
111 address and any of several 8-bit registers for the low 8
112 bits. AltOS uses a few bits of this memory, it should
114 </p></div><div class="section" title="1.5. __code"><div class="titlepage"><div><div><h3 class="title"><a name="idp2387640"></a>1.5. __code</h3></div></div></div><p>
115 All executable code must live in this address space, but
116 you can stick read-only data here too. It is addressed
117 using the 16-bit address register and special 'code'
118 access opcodes. Anything read-only should live in this space.
119 </p></div><div class="section" title="1.6. __bit"><div class="titlepage"><div><div><h3 class="title"><a name="idp2712072"></a>1.6. __bit</h3></div></div></div><p>
120 The 8051 has 128 bits of bit-addressible memory that
121 lives in the __data segment from 0x20 through
122 0x2f. Special instructions access these bits
123 in a single atomic operation. This isn't so much a
124 separate address space as a special addressing mode for
125 a few bytes in the __data segment.
126 </p></div><div class="section" title="1.7. __sfr, __sfr16, __sfr32, __sbit"><div class="titlepage"><div><div><h3 class="title"><a name="idp2470984"></a>1.7. __sfr, __sfr16, __sfr32, __sbit</h3></div></div></div><p>
127 Access to physical registers in the device use this mode
128 which declares the variable name, it's type and the
129 address it lives at. No memory is allocated for these
131 </p></div></div><div class="section" title="2. Function calls on the 8051"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3567856"></a>2. Function calls on the 8051</h2></div></div></div><p>
132 Because stack addressing is expensive, and stack space
133 limited, the default function call declaration in SDCC
134 allocates all parameters and local variables in static global
135 memory. Just like fortran. This makes these functions
136 non-reentrant, and also consume space for parameters and
137 locals even when they are not running. The benefit is smaller
138 code and faster execution.
139 </p><div class="section" title="2.1. __reentrant functions"><div class="titlepage"><div><div><h3 class="title"><a name="idp3012760"></a>2.1. __reentrant functions</h3></div></div></div><p>
140 All functions which are re-entrant, either due to recursion
141 or due to a potential context switch while executing, should
142 be marked as __reentrant so that their parameters and local
143 variables get allocated on the stack. This ensures that
144 these values are not overwritten by another invocation of
147 Functions which use significant amounts of space for
148 arguments and/or local variables and which are not often
149 invoked can also be marked as __reentrant. The resulting
150 code will be larger, but the savings in memory are
151 frequently worthwhile.
152 </p></div><div class="section" title="2.2. Non __reentrant functions"><div class="titlepage"><div><div><h3 class="title"><a name="idp3274328"></a>2.2. Non __reentrant functions</h3></div></div></div><p>
153 All parameters and locals in non-reentrant functions can
154 have data space decoration so that they are allocated in
155 __xdata, __pdata or __data space as desired. This can avoid
156 consuming __data space for infrequently used variables in
157 frequently used functions.
159 All library functions called by SDCC, including functions
160 for multiplying and dividing large data types, are
161 non-reentrant. Because of this, interrupt handlers must not
162 invoke any library functions, including the multiply and
164 </p></div><div class="section" title="2.3. __interrupt functions"><div class="titlepage"><div><div><h3 class="title"><a name="idp1868232"></a>2.3. __interrupt functions</h3></div></div></div><p>
165 Interrupt functions are declared with with an __interrupt
166 decoration that includes the interrupt number. SDCC saves
167 and restores all of the registers in these functions and
168 uses the 'reti' instruction at the end so that they operate
169 as stand-alone interrupt handlers. Interrupt functions may
170 call the ao_wakeup function to wake AltOS tasks.
171 </p></div><div class="section" title="2.4. __critical functions and statements"><div class="titlepage"><div><div><h3 class="title"><a name="idp2323224"></a>2.4. __critical functions and statements</h3></div></div></div><p>
172 SDCC has built-in support for suspending interrupts during
173 critical code. Functions marked as __critical will have
174 interrupts suspended for the whole period of
175 execution. Individual statements may also be marked as
176 __critical which blocks interrupts during the execution of
177 that statement. Keeping critical sections as short as
178 possible is key to ensuring that interrupts are handled as
180 </p></div></div></div><div class="chapter" title="Chapter 3. Task functions"><div class="titlepage"><div><div><h2 class="title"><a name="idp2522240"></a>Chapter 3. Task functions</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#idp1968112">1. ao_add_task</a></span></dt><dt><span class="section"><a href="#idp3359576">2. ao_exit</a></span></dt><dt><span class="section"><a href="#idp3085968">3. ao_sleep</a></span></dt><dt><span class="section"><a href="#idp3004432">4. ao_wakeup</a></span></dt><dt><span class="section"><a href="#idp2423736">5. ao_alarm</a></span></dt><dt><span class="section"><a href="#idp2605456">6. ao_start_scheduler</a></span></dt><dt><span class="section"><a href="#idp3312896">7. ao_clock_init</a></span></dt></dl></div><p>
181 This chapter documents how to create, destroy and schedule AltOS tasks.
182 </p><div class="section" title="1. ao_add_task"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp1968112"></a>1. ao_add_task</h2></div></div></div><pre class="programlisting">
184 ao_add_task(__xdata struct ao_task * task,
188 This initializes the statically allocated task structure,
189 assigns a name to it (not used for anything but the task
190 display), and the start address. It does not switch to the
191 new task. 'start' must not ever return; there is no place
193 </p></div><div class="section" title="2. ao_exit"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3359576"></a>2. ao_exit</h2></div></div></div><pre class="programlisting">
197 This terminates the current task.
198 </p></div><div class="section" title="3. ao_sleep"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3085968"></a>3. ao_sleep</h2></div></div></div><pre class="programlisting">
200 ao_sleep(__xdata void *wchan)
202 This suspends the current task until 'wchan' is signaled
203 by ao_wakeup, or until the timeout, set by ao_alarm,
204 fires. If 'wchan' is signaled, ao_sleep returns 0, otherwise
205 it returns 1. This is the only way to switch to another task.
207 Because ao_wakeup wakes every task waiting on a particular
208 location, ao_sleep should be used in a loop that first
209 checks the desired condition, blocks in ao_sleep and then
210 rechecks until the condition is satisfied. If the
211 location may be signaled from an interrupt handler, the
212 code will need to block interrupts by using the __critical
213 label around the block of code. Here's a complete example:
214 </p><pre class="programlisting">
215 __critical while (!ao_radio_done)
216 ao_sleep(&ao_radio_done);
218 </p></div><div class="section" title="4. ao_wakeup"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3004432"></a>4. ao_wakeup</h2></div></div></div><pre class="programlisting">
220 ao_wakeup(__xdata void *wchan)
222 Wake all tasks blocked on 'wchan'. This makes them
223 available to be run again, but does not actually switch
224 to another task. Here's an example of using this:
225 </p><pre class="programlisting">
226 if (RFIF & RFIF_IM_DONE) {
228 ao_wakeup(&ao_radio_done);
229 RFIF &= ~RFIF_IM_DONE;
232 Note that this need not be enclosed in __critical as the
233 ao_sleep block can only be run from normal mode, and so
234 this sequence can never be interrupted with execution of
236 </p></div><div class="section" title="5. ao_alarm"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2423736"></a>5. ao_alarm</h2></div></div></div><pre class="programlisting">
238 ao_alarm(uint16_t delay)
240 Schedules an alarm to fire in at least 'delay' ticks. If
241 the task is asleep when the alarm fires, it will wakeup
242 and ao_sleep will return 1.
243 </p><pre class="programlisting">
244 ao_alarm(ao_packet_master_delay);
245 __critical while (!ao_radio_dma_done)
246 if (ao_sleep(&ao_radio_dma_done) != 0)
249 In this example, a timeout is set before waiting for
250 incoming radio data. If no data is received before the
251 timeout fires, ao_sleep will return 1 and then this code
252 will abort the radio receive operation.
253 </p></div><div class="section" title="6. ao_start_scheduler"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2605456"></a>6. ao_start_scheduler</h2></div></div></div><pre class="programlisting">
255 ao_start_scheduler(void)
257 This is called from 'main' when the system is all
258 initialized and ready to run. It will not return.
259 </p></div><div class="section" title="7. ao_clock_init"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3312896"></a>7. ao_clock_init</h2></div></div></div><pre class="programlisting">
263 This turns on the external 48MHz clock then switches the
264 hardware to using it. This is required by many of the
265 internal devices like USB. It should be called by the
266 'main' function first, before initializing any of the
267 other devices in the system.
268 </p></div></div><div class="chapter" title="Chapter 4. Timer Functions"><div class="titlepage"><div><div><h2 class="title"><a name="idp2103648"></a>Chapter 4. Timer Functions</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#idp2407008">1. ao_time</a></span></dt><dt><span class="section"><a href="#idp2512832">2. ao_delay</a></span></dt><dt><span class="section"><a href="#idp2252856">3. ao_timer_set_adc_interval</a></span></dt><dt><span class="section"><a href="#idp3005352">4. ao_timer_init</a></span></dt></dl></div><p>
269 AltOS sets up one of the cc1111 timers to run at 100Hz and
270 exposes this tick as the fundemental unit of time. At each
271 interrupt, AltOS increments the counter, and schedules any tasks
272 waiting for that time to pass, then fires off the ADC system to
273 collect current data readings. Doing this from the ISR ensures
274 that the ADC values are sampled at a regular rate, independent
275 of any scheduling jitter.
276 </p><div class="section" title="1. ao_time"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2407008"></a>1. ao_time</h2></div></div></div><pre class="programlisting">
280 Returns the current system tick count. Note that this is
281 only a 16 bit value, and so it wraps every 655.36 seconds.
282 </p></div><div class="section" title="2. ao_delay"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2512832"></a>2. ao_delay</h2></div></div></div><pre class="programlisting">
284 ao_delay(uint16_t ticks);
286 Suspend the current task for at least 'ticks' clock units.
287 </p></div><div class="section" title="3. ao_timer_set_adc_interval"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2252856"></a>3. ao_timer_set_adc_interval</h2></div></div></div><pre class="programlisting">
289 ao_timer_set_adc_interval(uint8_t interval);
291 This sets the number of ticks between ADC samples. If set
292 to 0, no ADC samples are generated. AltOS uses this to
293 slow down the ADC sampling rate to save power.
294 </p></div><div class="section" title="4. ao_timer_init"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3005352"></a>4. ao_timer_init</h2></div></div></div><pre class="programlisting">
298 This turns on the 100Hz tick using the CC1111 timer 1. It
299 is required for any of the time-based functions to
300 work. It should be called by 'main' before ao_start_scheduler.
301 </p></div></div><div class="chapter" title="Chapter 5. AltOS Mutexes"><div class="titlepage"><div><div><h2 class="title"><a name="idp3256712"></a>Chapter 5. AltOS Mutexes</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#idp2419784">1. ao_mutex_get</a></span></dt><dt><span class="section"><a href="#idp3558880">2. ao_mutex_put</a></span></dt></dl></div><p>
302 AltOS provides mutexes as a basic synchronization primitive. Each
303 mutexes is simply a byte of memory which holds 0 when the mutex
304 is free or the task id of the owning task when the mutex is
305 owned. Mutex calls are checked—attempting to acquire a mutex
306 already held by the current task or releasing a mutex not held
307 by the current task will both cause a panic.
308 </p><div class="section" title="1. ao_mutex_get"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2419784"></a>1. ao_mutex_get</h2></div></div></div><pre class="programlisting">
310 ao_mutex_get(__xdata uint8_t *mutex);
312 Acquires the specified mutex, blocking if the mutex is
313 owned by another task.
314 </p></div><div class="section" title="2. ao_mutex_put"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3558880"></a>2. ao_mutex_put</h2></div></div></div><pre class="programlisting">
316 ao_mutex_put(__xdata uint8_t *mutex);
318 Releases the specified mutex, waking up all tasks waiting
320 </p></div></div><div class="chapter" title="Chapter 6. CC1111 DMA engine"><div class="titlepage"><div><div><h2 class="title"><a name="idp1927912"></a>Chapter 6. CC1111 DMA engine</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#idp3033536">1. ao_dma_alloc</a></span></dt><dt><span class="section"><a href="#idp3322920">2. ao_dma_set_transfer</a></span></dt><dt><span class="section"><a href="#idp2415360">3. ao_dma_start</a></span></dt><dt><span class="section"><a href="#idp2383728">4. ao_dma_trigger</a></span></dt><dt><span class="section"><a href="#idp1636944">5. ao_dma_abort</a></span></dt></dl></div><p>
321 The CC1111 contains a useful bit of extra hardware in the form
322 of five programmable DMA engines. They can be configured to copy
323 data in memory, or between memory and devices (or even between
324 two devices). AltOS exposes a general interface to this hardware
325 and uses it to handle radio and SPI data.
327 Code using a DMA engine should allocate one at startup
328 time. There is no provision to free them, and if you run out,
329 AltOS will simply panic.
331 During operation, the DMA engine is initialized with the
332 transfer parameters. Then it is started, at which point it
333 awaits a suitable event to start copying data. When copying data
334 from hardware to memory, that trigger event is supplied by the
335 hardware device. When copying data from memory to hardware, the
336 transfer is usually initiated by software.
337 </p><div class="section" title="1. ao_dma_alloc"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3033536"></a>1. ao_dma_alloc</h2></div></div></div><pre class="programlisting">
339 ao_dma_alloc(__xdata uint8_t *done)
341 Allocates a DMA engine, returning the identifier. Whenever
342 this DMA engine completes a transfer. 'done' is cleared
343 when the DMA is started, and then receives the
344 AO_DMA_DONE bit on a successful transfer or the
345 AO_DMA_ABORTED bit if ao_dma_abort was called. Note that
346 it is possible to get both bits if the transfer was
347 aborted after it had finished.
348 </p></div><div class="section" title="2. ao_dma_set_transfer"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3322920"></a>2. ao_dma_set_transfer</h2></div></div></div><pre class="programlisting">
350 ao_dma_set_transfer(uint8_t id,
351 void __xdata *srcaddr,
352 void __xdata *dstaddr,
357 Initializes the specified dma engine to copy data
358 from 'srcaddr' to 'dstaddr' for 'count' units. cfg0 and
359 cfg1 are values directly out of the CC1111 documentation
360 and tell the DMA engine what the transfer unit size,
361 direction and step are.
362 </p></div><div class="section" title="3. ao_dma_start"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2415360"></a>3. ao_dma_start</h2></div></div></div><pre class="programlisting">
364 ao_dma_start(uint8_t id);
366 Arm the specified DMA engine and await a signal from
367 either hardware or software to start transferring data.
368 </p></div><div class="section" title="4. ao_dma_trigger"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2383728"></a>4. ao_dma_trigger</h2></div></div></div><pre class="programlisting">
370 ao_dma_trigger(uint8_t id)
372 Trigger the specified DMA engine to start copying data.
373 </p></div><div class="section" title="5. ao_dma_abort"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp1636944"></a>5. ao_dma_abort</h2></div></div></div><pre class="programlisting">
375 ao_dma_abort(uint8_t id)
377 Terminate any in-progress DMA transation, marking its
378 'done' variable with the AO_DMA_ABORTED bit.
379 </p></div></div><div class="chapter" title="Chapter 7. SDCC Stdio interface"><div class="titlepage"><div><div><h2 class="title"><a name="idp3215304"></a>Chapter 7. SDCC Stdio interface</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#idp2502672">1. putchar</a></span></dt><dt><span class="section"><a href="#idp2459944">2. getchar</a></span></dt><dt><span class="section"><a href="#idp2914760">3. flush</a></span></dt><dt><span class="section"><a href="#idp2873064">4. ao_add_stdio</a></span></dt></dl></div><p>
380 AltOS offers a stdio interface over both USB and the RF packet
381 link. This provides for control of the device localy or
382 remotely. This is hooked up to the stdio functions in SDCC by
383 providing the standard putchar/getchar/flush functions. These
384 automatically multiplex the two available communication
385 channels; output is always delivered to the channel which
386 provided the most recent input.
387 </p><div class="section" title="1. putchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2502672"></a>1. putchar</h2></div></div></div><pre class="programlisting">
391 Delivers a single character to the current console
393 </p></div><div class="section" title="2. getchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2459944"></a>2. getchar</h2></div></div></div><pre class="programlisting">
397 Reads a single character from any of the available
398 console devices. The current console device is set to
399 that which delivered this character. This blocks until
400 a character is available.
401 </p></div><div class="section" title="3. flush"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2914760"></a>3. flush</h2></div></div></div><pre class="programlisting">
405 Flushes the current console device output buffer. Any
406 pending characters will be delivered to the target device.
407 xo </p></div><div class="section" title="4. ao_add_stdio"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2873064"></a>4. ao_add_stdio</h2></div></div></div><pre class="programlisting">
409 ao_add_stdio(char (*pollchar)(void),
410 void (*putchar)(char),
413 This adds another console device to the available
416 'pollchar' returns either an available character or
417 AO_READ_AGAIN if none is available. Significantly, it does
418 not block. The device driver must set 'ao_stdin_ready' to
419 1 and call ao_wakeup(&ao_stdin_ready) when it receives
420 input to tell getchar that more data is available, at
421 which point 'pollchar' will be called again.
423 'putchar' queues a character for output, flushing if the output buffer is
424 full. It may block in this case.
426 'flush' forces the output buffer to be flushed. It may
427 block until the buffer is delivered, but it is not
429 </p></div></div><div class="chapter" title="Chapter 8. Command line interface"><div class="titlepage"><div><div><h2 class="title"><a name="idp2170912"></a>Chapter 8. Command line interface</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#idp3529992">1. ao_cmd_register</a></span></dt><dt><span class="section"><a href="#idp2645232">2. ao_cmd_lex</a></span></dt><dt><span class="section"><a href="#idp2564824">3. ao_cmd_put16</a></span></dt><dt><span class="section"><a href="#idp3113528">4. ao_cmd_put8</a></span></dt><dt><span class="section"><a href="#idp1935488">5. ao_cmd_white</a></span></dt><dt><span class="section"><a href="#idp1896024">6. ao_cmd_hex</a></span></dt><dt><span class="section"><a href="#idp2433952">7. ao_cmd_decimal</a></span></dt><dt><span class="section"><a href="#idp2883960">8. ao_match_word</a></span></dt><dt><span class="section"><a href="#idp3489544">9. ao_cmd_init</a></span></dt></dl></div><p>
430 AltOS includes a simple command line parser which is hooked up
431 to the stdio interfaces permitting remote control of the device
432 over USB or the RF link as desired. Each command uses a single
433 character to invoke it, the remaining characters on the line are
434 available as parameters to the command.
435 </p><div class="section" title="1. ao_cmd_register"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3529992"></a>1. ao_cmd_register</h2></div></div></div><pre class="programlisting">
437 ao_cmd_register(__code struct ao_cmds *cmds)
439 This registers a set of commands with the command
440 parser. There is a fixed limit on the number of command
441 sets, the system will panic if too many are registered.
442 Each command is defined by a struct ao_cmds entry:
443 </p><pre class="programlisting">
450 'cmd' is the character naming the command. 'func' is the
451 function to invoke and 'help' is a string displayed by the
452 '?' command. Syntax errors found while executing 'func'
453 should be indicated by modifying the global ao_cmd_status
454 variable with one of the following values:
455 </p><div class="variablelist"><dl><dt></dt><dd><p>
456 The command was parsed successfully. There is no
457 need to assign this value, it is the default.
458 </p></dd><dt></dt><dd><p>
459 A token in the line was invalid, such as a number
460 containing invalid characters. The low-level
461 lexing functions already assign this value as needed.
462 </p></dd><dt></dt><dd><p>
463 The command line is invalid for some reason other
465 </p></dd></dl></div><p>
466 </p></div><div class="section" title="2. ao_cmd_lex"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2645232"></a>2. ao_cmd_lex</h2></div></div></div><pre class="programlisting">
470 This gets the next character out of the command line
471 buffer and sticks it into ao_cmd_lex_c. At the end of the
472 line, ao_cmd_lex_c will get a newline ('\n') character.
473 </p></div><div class="section" title="3. ao_cmd_put16"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2564824"></a>3. ao_cmd_put16</h2></div></div></div><pre class="programlisting">
475 ao_cmd_put16(uint16_t v);
477 Writes 'v' as four hexadecimal characters.
478 </p></div><div class="section" title="4. ao_cmd_put8"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3113528"></a>4. ao_cmd_put8</h2></div></div></div><pre class="programlisting">
480 ao_cmd_put8(uint8_t v);
482 Writes 'v' as two hexadecimal characters.
483 </p></div><div class="section" title="5. ao_cmd_white"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp1935488"></a>5. ao_cmd_white</h2></div></div></div><pre class="programlisting">
487 This skips whitespace by calling ao_cmd_lex while
488 ao_cmd_lex_c is either a space or tab. It does not skip
489 any characters if ao_cmd_lex_c already non-white.
490 </p></div><div class="section" title="6. ao_cmd_hex"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp1896024"></a>6. ao_cmd_hex</h2></div></div></div><pre class="programlisting">
494 This reads a 16-bit hexadecimal value from the command
495 line with optional leading whitespace. The resulting value
496 is stored in ao_cmd_lex_i;
497 </p></div><div class="section" title="7. ao_cmd_decimal"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2433952"></a>7. ao_cmd_decimal</h2></div></div></div><pre class="programlisting">
501 This reads a 32-bit decimal value from the command
502 line with optional leading whitespace. The resulting value
503 is stored in ao_cmd_lex_u32 and the low 16 bits are stored
505 </p></div><div class="section" title="8. ao_match_word"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2883960"></a>8. ao_match_word</h2></div></div></div><pre class="programlisting">
507 ao_match_word(__code char *word)
509 This checks to make sure that 'word' occurs on the command
510 line. It does not skip leading white space. If 'word' is
511 found, then 1 is returned. Otherwise, ao_cmd_status is set to
512 ao_cmd_syntax_error and 0 is returned.
513 </p></div><div class="section" title="9. ao_cmd_init"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3489544"></a>9. ao_cmd_init</h2></div></div></div><pre class="programlisting">
517 Initializes the command system, setting up the built-in
518 commands and adding a task to run the command processing
519 loop. It should be called by 'main' before ao_start_scheduler.
520 </p></div></div><div class="chapter" title="Chapter 9. CC1111 USB target device"><div class="titlepage"><div><div><h2 class="title"><a name="idp2151344"></a>Chapter 9. CC1111 USB target device</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#idp2038816">1. ao_usb_flush</a></span></dt><dt><span class="section"><a href="#idp2901984">2. ao_usb_putchar</a></span></dt><dt><span class="section"><a href="#idp1930120">3. ao_usb_pollchar</a></span></dt><dt><span class="section"><a href="#idp2176008">4. ao_usb_getchar</a></span></dt><dt><span class="section"><a href="#idp1694928">5. ao_usb_disable</a></span></dt><dt><span class="section"><a href="#idp2859448">6. ao_usb_enable</a></span></dt><dt><span class="section"><a href="#idp2323496">7. ao_usb_init</a></span></dt></dl></div><p>
521 The CC1111 contains a full-speed USB target device. It can be
522 programmed to offer any kind of USB target, but to simplify
523 interactions with a variety of operating systems, AltOS provides
524 only a single target device profile, that of a USB modem which
525 has native drivers for Linux, Windows and Mac OS X. It would be
526 easy to change the code to provide an alternate target device if
529 To the rest of the system, the USB device looks like a simple
530 two-way byte stream. It can be hooked into the command line
531 interface if desired, offering control of the device over the
532 USB link. Alternatively, the functions can be accessed directly
533 to provide for USB-specific I/O.
534 </p><div class="section" title="1. ao_usb_flush"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2038816"></a>1. ao_usb_flush</h2></div></div></div><pre class="programlisting">
538 Flushes any pending USB output. This queues an 'IN' packet
539 to be delivered to the USB host if there is pending data,
540 or if the last IN packet was full to indicate to the host
541 that there isn't any more pending data available.
542 </p></div><div class="section" title="2. ao_usb_putchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2901984"></a>2. ao_usb_putchar</h2></div></div></div><pre class="programlisting">
544 ao_usb_putchar(char c);
546 If there is a pending 'IN' packet awaiting delivery to the
547 host, this blocks until that has been fetched. Then, this
548 adds a byte to the pending IN packet for delivery to the
549 USB host. If the USB packet is full, this queues the 'IN'
551 </p></div><div class="section" title="3. ao_usb_pollchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp1930120"></a>3. ao_usb_pollchar</h2></div></div></div><pre class="programlisting">
553 ao_usb_pollchar(void);
555 If there are no characters remaining in the last 'OUT'
556 packet received, this returns AO_READ_AGAIN. Otherwise, it
557 returns the next character, reporting to the host that it
558 is ready for more data when the last character is gone.
559 </p></div><div class="section" title="4. ao_usb_getchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2176008"></a>4. ao_usb_getchar</h2></div></div></div><pre class="programlisting">
561 ao_usb_getchar(void);
563 This uses ao_pollchar to receive the next character,
564 blocking while ao_pollchar returns AO_READ_AGAIN.
565 </p></div><div class="section" title="5. ao_usb_disable"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp1694928"></a>5. ao_usb_disable</h2></div></div></div><pre class="programlisting">
567 ao_usb_disable(void);
569 This turns off the USB controller. It will no longer
570 respond to host requests, nor return characters. Calling
571 any of the i/o routines while the USB device is disabled
572 is undefined, and likely to break things. Disabling the
573 USB device when not needed saves power.
575 Note that neither TeleDongle nor TeleMetrum are able to
576 signal to the USB host that they have disconnected, so
577 after disabling the USB device, it's likely that the cable
578 will need to be disconnected and reconnected before it
580 </p></div><div class="section" title="6. ao_usb_enable"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2859448"></a>6. ao_usb_enable</h2></div></div></div><pre class="programlisting">
584 This turns the USB controller on again after it has been
585 disabled. See the note above about needing to physically
586 remove and re-insert the cable to get the host to
587 re-initialize the USB link.
588 </p></div><div class="section" title="7. ao_usb_init"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2323496"></a>7. ao_usb_init</h2></div></div></div><pre class="programlisting">
592 This turns the USB controller on, adds a task to handle
593 the control end point and adds the usb I/O functions to
594 the stdio system. Call this from main before
596 </p></div></div><div class="chapter" title="Chapter 10. CC1111 Serial peripheral"><div class="titlepage"><div><div><h2 class="title"><a name="idp3103048"></a>Chapter 10. CC1111 Serial peripheral</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#idp864464">1. ao_serial_getchar</a></span></dt><dt><span class="section"><a href="#idp2883824">2. ao_serial_putchar</a></span></dt><dt><span class="section"><a href="#idp1519672">3. ao_serial_drain</a></span></dt><dt><span class="section"><a href="#idp2341432">4. ao_serial_set_speed</a></span></dt><dt><span class="section"><a href="#idp1472312">5. ao_serial_init</a></span></dt></dl></div><p>
597 The CC1111 provides two USART peripherals. AltOS uses one for
598 asynch serial data, generally to communicate with a GPS device,
599 and the other for a SPI bus. The UART is configured to operate
600 in 8-bits, no parity, 1 stop bit framing. The default
601 configuration has clock settings for 4800, 9600 and 57600 baud
602 operation. Additional speeds can be added by computing
603 appropriate clock values.
605 To prevent loss of data, AltOS provides receive and transmit
606 fifos of 32 characters each.
607 </p><div class="section" title="1. ao_serial_getchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp864464"></a>1. ao_serial_getchar</h2></div></div></div><pre class="programlisting">
609 ao_serial_getchar(void);
611 Returns the next character from the receive fifo, blocking
612 until a character is received if the fifo is empty.
613 </p></div><div class="section" title="2. ao_serial_putchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2883824"></a>2. ao_serial_putchar</h2></div></div></div><pre class="programlisting">
615 ao_serial_putchar(char c);
617 Adds a character to the transmit fifo, blocking if the
618 fifo is full. Starts transmitting characters.
619 </p></div><div class="section" title="3. ao_serial_drain"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp1519672"></a>3. ao_serial_drain</h2></div></div></div><pre class="programlisting">
621 ao_serial_drain(void);
623 Blocks until the transmit fifo is empty. Used internally
624 when changing serial speeds.
625 </p></div><div class="section" title="4. ao_serial_set_speed"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2341432"></a>4. ao_serial_set_speed</h2></div></div></div><pre class="programlisting">
627 ao_serial_set_speed(uint8_t speed);
629 Changes the serial baud rate to one of
630 AO_SERIAL_SPEED_4800, AO_SERIAL_SPEED_9600 or
631 AO_SERIAL_SPEED_57600. This first flushes the transmit
632 fifo using ao_serial_drain.
633 </p></div><div class="section" title="5. ao_serial_init"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp1472312"></a>5. ao_serial_init</h2></div></div></div><pre class="programlisting">
637 Initializes the serial peripheral. Call this from 'main'
638 before jumping to ao_start_scheduler. The default speed
639 setting is AO_SERIAL_SPEED_4800.
640 </p></div></div><div class="chapter" title="Chapter 11. CC1111 Radio peripheral"><div class="titlepage"><div><div><h2 class="title"><a name="idp1597944"></a>Chapter 11. CC1111 Radio peripheral</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#idp2842880">1. ao_radio_set_telemetry</a></span></dt><dt><span class="section"><a href="#idp2488848">2. ao_radio_set_packet</a></span></dt><dt><span class="section"><a href="#idp3223464">3. ao_radio_set_rdf</a></span></dt><dt><span class="section"><a href="#idp3006000">4. ao_radio_idle</a></span></dt><dt><span class="section"><a href="#idp2577544">5. ao_radio_get</a></span></dt><dt><span class="section"><a href="#idp2990720">6. ao_radio_put</a></span></dt><dt><span class="section"><a href="#idp2892440">7. ao_radio_abort</a></span></dt><dt><span class="section"><a href="#idp2871216">8. ao_radio_send</a></span></dt><dt><span class="section"><a href="#idp2464440">9. ao_radio_recv</a></span></dt><dt><span class="section"><a href="#idp2485328">10. ao_radio_rdf</a></span></dt><dt><span class="section"><a href="#idp2075376">11. ao_packet_putchar</a></span></dt><dt><span class="section"><a href="#idp2237088">12. ao_packet_pollchar</a></span></dt><dt><span class="section"><a href="#idp2384480">13. ao_packet_slave_start</a></span></dt><dt><span class="section"><a href="#idp2780480">14. ao_packet_slave_stop</a></span></dt><dt><span class="section"><a href="#idp2387432">15. ao_packet_slave_init</a></span></dt><dt><span class="section"><a href="#idp2526032">16. ao_packet_master_init</a></span></dt></dl></div><p>
641 The CC1111 radio transceiver sends and receives digital packets
642 with forward error correction and detection. The AltOS driver is
643 fairly specific to the needs of the TeleMetrum and TeleDongle
644 devices, using it for other tasks may require customization of
645 the driver itself. There are three basic modes of operation:
646 </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
647 Telemetry mode. In this mode, TeleMetrum transmits telemetry
648 frames at a fixed rate. The frames are of fixed size. This
649 is strictly a one-way communication from TeleMetrum to
651 </p></li><li class="listitem"><p>
652 Packet mode. In this mode, the radio is used to create a
653 reliable duplex byte stream between TeleDongle and
654 TeleMetrum. This is an asymmetrical protocol with
655 TeleMetrum only transmitting in response to a packet sent
656 from TeleDongle. Thus getting data from TeleMetrum to
657 TeleDongle requires polling. The polling rate is adaptive,
658 when no data has been received for a while, the rate slows
659 down. The packets are checked at both ends and invalid
662 On the TeleMetrum side, the packet link is hooked into the
663 stdio mechanism, providing an alternate data path for the
664 command processor. It is enabled when the unit boots up in
667 On the TeleDongle side, the packet link is enabled with a
668 command; data from the stdio package is forwarded over the
669 packet link providing a connection from the USB command
670 stream to the remote TeleMetrum device.
671 </p></li><li class="listitem"><p>
672 Radio Direction Finding mode. In this mode, TeleMetrum
673 constructs a special packet that sounds like an audio tone
674 when received by a conventional narrow-band FM
675 receiver. This is designed to provide a beacon to track
676 the device when other location mechanisms fail.
677 </p></li></ol></div><p>
678 </p><div class="section" title="1. ao_radio_set_telemetry"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2842880"></a>1. ao_radio_set_telemetry</h2></div></div></div><pre class="programlisting">
680 ao_radio_set_telemetry(void);
682 Configures the radio to send or receive telemetry
683 packets. This includes packet length, modulation scheme and
684 other RF parameters. It does not include the base frequency
685 or channel though. Those are set at the time of transmission
686 or reception, in case the values are changed by the user.
687 </p></div><div class="section" title="2. ao_radio_set_packet"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2488848"></a>2. ao_radio_set_packet</h2></div></div></div><pre class="programlisting">
689 ao_radio_set_packet(void);
691 Configures the radio to send or receive packet data. This
692 includes packet length, modulation scheme and other RF
693 parameters. It does not include the base frequency or
694 channel though. Those are set at the time of transmission or
695 reception, in case the values are changed by the user.
696 </p></div><div class="section" title="3. ao_radio_set_rdf"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3223464"></a>3. ao_radio_set_rdf</h2></div></div></div><pre class="programlisting">
698 ao_radio_set_rdf(void);
700 Configures the radio to send RDF 'packets'. An RDF 'packet'
701 is a sequence of hex 0x55 bytes sent at a base bit rate of
702 2kbps using a 5kHz deviation. All of the error correction
703 and data whitening logic is turned off so that the resulting
704 modulation is received as a 1kHz tone by a conventional 70cm
706 </p></div><div class="section" title="4. ao_radio_idle"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3006000"></a>4. ao_radio_idle</h2></div></div></div><pre class="programlisting">
710 Sets the radio device to idle mode, waiting until it reaches
711 that state. This will terminate any in-progress transmit or
713 </p></div><div class="section" title="5. ao_radio_get"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2577544"></a>5. ao_radio_get</h2></div></div></div><pre class="programlisting">
717 Acquires the radio mutex and then configures the radio
718 frequency using the global radio calibration and channel
720 </p></div><div class="section" title="6. ao_radio_put"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2990720"></a>6. ao_radio_put</h2></div></div></div><pre class="programlisting">
724 Releases the radio mutex.
725 </p></div><div class="section" title="7. ao_radio_abort"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2892440"></a>7. ao_radio_abort</h2></div></div></div><pre class="programlisting">
727 ao_radio_abort(void);
729 Aborts any transmission or reception process by aborting the
730 associated DMA object and calling ao_radio_idle to terminate
733 In telemetry mode, you can send or receive a telemetry
734 packet. The data from receiving a packet also includes the RSSI
735 and status values supplied by the receiver. These are added
736 after the telemetry data.
737 </p><div class="section" title="8. ao_radio_send"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2871216"></a>8. ao_radio_send</h2></div></div></div><pre class="programlisting">
739 ao_radio_send(__xdata struct ao_telemetry *telemetry);
741 This sends the specific telemetry packet, waiting for the
742 transmission to complete. The radio must have been set to
743 telemetry mode. This function calls ao_radio_get() before
744 sending, and ao_radio_put() afterwards, to correctly
745 serialize access to the radio device.
746 </p></div><div class="section" title="9. ao_radio_recv"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2464440"></a>9. ao_radio_recv</h2></div></div></div><pre class="programlisting">
748 ao_radio_recv(__xdata struct ao_radio_recv *radio);
750 This blocks waiting for a telemetry packet to be received.
751 The radio must have been set to telemetry mode. This
752 function calls ao_radio_get() before receiving, and
753 ao_radio_put() afterwards, to correctly serialize access
754 to the radio device. This returns non-zero if a packet was
755 received, or zero if the operation was aborted (from some
756 other task calling ao_radio_abort()).
758 In radio direction finding mode, there's just one function to
760 </p><div class="section" title="10. ao_radio_rdf"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2485328"></a>10. ao_radio_rdf</h2></div></div></div><pre class="programlisting">
762 ao_radio_rdf(int ms);
764 This sends an RDF packet lasting for the specified amount
765 of time. The maximum length is 1020 ms.
767 Packet mode is asymmetrical and is configured at compile time
768 for either master or slave mode (but not both). The basic I/O
769 functions look the same at both ends, but the internals are
770 different, along with the initialization steps.
771 </p><div class="section" title="11. ao_packet_putchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2075376"></a>11. ao_packet_putchar</h2></div></div></div><pre class="programlisting">
773 ao_packet_putchar(char c);
775 If the output queue is full, this first blocks waiting for
776 that data to be delivered. Then, queues a character for
777 packet transmission. On the master side, this will
778 transmit a packet if the output buffer is full. On the
779 slave side, any pending data will be sent the next time
780 the master polls for data.
781 </p></div><div class="section" title="12. ao_packet_pollchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2237088"></a>12. ao_packet_pollchar</h2></div></div></div><pre class="programlisting">
783 ao_packet_pollchar(void);
785 This returns a pending input character if available,
786 otherwise returns AO_READ_AGAIN. On the master side, if
787 this empties the buffer, it triggers a poll for more data.
788 </p></div><div class="section" title="13. ao_packet_slave_start"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2384480"></a>13. ao_packet_slave_start</h2></div></div></div><pre class="programlisting">
790 ao_packet_slave_start(void);
792 This is available only on the slave side and starts a task
793 to listen for packet data.
794 </p></div><div class="section" title="14. ao_packet_slave_stop"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2780480"></a>14. ao_packet_slave_stop</h2></div></div></div><pre class="programlisting">
796 ao_packet_slave_stop(void);
798 Disables the packet slave task, stopping the radio receiver.
799 </p></div><div class="section" title="15. ao_packet_slave_init"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2387432"></a>15. ao_packet_slave_init</h2></div></div></div><pre class="programlisting">
801 ao_packet_slave_init(void);
803 Adds the packet stdio functions to the stdio package so
804 that when packet slave mode is enabled, characters will
805 get send and received through the stdio functions.
806 </p></div><div class="section" title="16. ao_packet_master_init"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2526032"></a>16. ao_packet_master_init</h2></div></div></div><pre class="programlisting">
808 ao_packet_master_init(void);
810 Adds the 'p' packet forward command to start packet mode.
811 </p></div></div></div></body></html>
projects / web / altusmetrum / blob