1 <?xml version="1.0" encoding="utf-8" ?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd">
7 <subtitle>Altos Metrum Operating System</subtitle>
10 <firstname>Keith</firstname>
11 <surname>Packard</surname>
15 <holder>Keith Packard</holder>
19 This document is released under the terms of the
20 <ulink url="http://creativecommons.org/licenses/by-sa/3.0/">
21 Creative Commons ShareAlike 3.0
28 <revnumber>0.1</revnumber>
29 <date>22 November 2010</date>
30 <revremark>Initial content</revremark>
35 <title>Overview</title>
37 AltOS is a operating system built for the 8051-compatible
38 processor found in the TI cc1111 microcontroller. It's designed
39 to be small and easy to program with. The main features are:
42 <para>Multi-tasking. While the 8051 doesn't provide separate
43 address spaces, it's often easier to write code that operates
44 in separate threads instead of tying everything into one giant
49 <para>Non-preemptive. This increases latency for thread
50 switching but reduces the number of places where context
51 switching can occur. It also simplifies the operating system
52 design somewhat. Nothing in the target system (rocket flight
53 control) has tight timing requirements, and so this seems like
54 a reasonable compromise.
58 <para>Sleep/wakeup scheduling. Taken directly from ancient
59 Unix designs, these two provide the fundemental scheduling
60 primitive within AltOS.
64 <para>Mutexes. As a locking primitive, mutexes are easier to
65 use than semaphores, at least in my experience.
69 <para>Timers. Tasks can set an alarm which will abort any
70 pending sleep, allowing operations to time-out instead of
77 The device drivers and other subsystems in AltOS are
78 conventionally enabled by invoking their _init() function from
79 the 'main' function before that calls
80 ao_start_scheduler(). These functions initialize the pin
81 assignments, add various commands to the command processor and
82 may add tasks to the scheduler to handle the device. A typical
83 main program, thus, looks like:
90 /* Turn on the LED until the system is stable */
91 ao_led_init(LEDS_AVAILABLE);
92 ao_led_on(AO_LED_RED);
96 ao_monitor_init(AO_LED_GREEN, TRUE);
97 ao_rssi_init(AO_LED_RED);
99 ao_packet_slave_init();
100 ao_packet_master_init();
105 ao_start_scheduler();
108 As you can see, a long sequence of subsystems are initialized
109 and then the scheduler is started.
113 <title>Programming the 8051 with SDCC</title>
115 The 8051 is a primitive 8-bit processor, designed in the mists
116 of time in as few transistors as possible. The architecture is
117 highly irregular and includes several separate memory
118 spaces. Furthermore, accessing stack variables is slow, and the
119 stack itself is of limited size. While SDCC papers over the
120 instruction set, it is not completely able to hide the memory
121 architecture from the application designer.
124 <title>8051 memory spaces</title>
126 The __data/__xdata/__code memory spaces below were completely
127 separate in the original 8051 design. In the cc1111, this
128 isn't true—they all live in a single unified 64kB address
129 space, and so it's possible to convert any address into a
130 unique 16-bit address. SDCC doesn't know this, and so a
131 'global' address to SDCC consumes 3 bytes of memory, 1 byte as
132 a tag indicating the memory space and 2 bytes of offset within
133 that space. AltOS avoids these 3-byte addresses as much as
134 possible; using them involves a function call per byte
135 access. The result is that nearly every variable declaration
136 is decorated with a memory space identifier which clutters the
137 code but makes the resulting code far smaller and more
141 <title>__data</title>
143 The 8051 can directly address these 128 bytes of
144 memory. This makes them precious so they should be
145 reserved for frequently addressed values. Oh, just to
146 confuse things further, the 8 general registers in the
147 CPU are actually stored in this memory space. There are
148 magic instructions to 'bank switch' among 4 banks of
149 these registers located at 0x00 - 0x1F. AltOS uses only
150 the first bank at 0x00 - 0x07, leaving the other 24
151 bytes available for other data.
155 <title>__idata</title>
157 There are an additional 128 bytes of internal memory
158 that share the same address space as __data but which
159 cannot be directly addressed. The stack normally
160 occupies this space and so AltOS doesn't place any
165 <title>__xdata</title>
167 This is additional general memory accessed through a
168 single 16-bit address register. The CC1111F32 has 32kB
169 of memory available here. Most program data should live
170 in this memory space.
174 <title>__pdata</title>
176 This is an alias for the first 256 bytes of __xdata
177 memory, but uses a shorter addressing mode with
178 single global 8-bit value for the high 8 bits of the
179 address and any of several 8-bit registers for the low 8
180 bits. AltOS uses a few bits of this memory, it should
185 <title>__code</title>
187 All executable code must live in this address space, but
188 you can stick read-only data here too. It is addressed
189 using the 16-bit address register and special 'code'
190 access opcodes. Anything read-only should live in this space.
196 The 8051 has 128 bits of bit-addressible memory that
197 lives in the __data segment from 0x20 through
198 0x2f. Special instructions access these bits
199 in a single atomic operation. This isn't so much a
200 separate address space as a special addressing mode for
201 a few bytes in the __data segment.
205 <title>__sfr, __sfr16, __sfr32, __sbit</title>
207 Access to physical registers in the device use this mode
208 which declares the variable name, it's type and the
209 address it lives at. No memory is allocated for these
215 <title>Function calls on the 8051</title>
217 Because stack addressing is expensive, and stack space
218 limited, the default function call declaration in SDCC
219 allocates all parameters and local variables in static global
220 memory. Just like fortran. This makes these functions
221 non-reentrant, and also consume space for parameters and
222 locals even when they are not running. The benefit is smaller
223 code and faster execution.
226 <title>__reentrant functions</title>
228 All functions which are re-entrant, either due to recursion
229 or due to a potential context switch while executing, should
230 be marked as __reentrant so that their parameters and local
231 variables get allocated on the stack. This ensures that
232 these values are not overwritten by another invocation of
236 Functions which use significant amounts of space for
237 arguments and/or local variables and which are not often
238 invoked can also be marked as __reentrant. The resulting
239 code will be larger, but the savings in memory are
240 frequently worthwhile.
244 <title>Non __reentrant functions</title>
246 All parameters and locals in non-reentrant functions can
247 have data space decoration so that they are allocated in
248 __xdata, __pdata or __data space as desired. This can avoid
249 consuming __data space for infrequently used variables in
250 frequently used functions.
253 All library functions called by SDCC, including functions
254 for multiplying and dividing large data types, are
255 non-reentrant. Because of this, interrupt handlers must not
256 invoke any library functions, including the multiply and
261 <title>__interrupt functions</title>
263 Interrupt functions are declared with with an __interrupt
264 decoration that includes the interrupt number. SDCC saves
265 and restores all of the registers in these functions and
266 uses the 'reti' instruction at the end so that they operate
267 as stand-alone interrupt handlers. Interrupt functions may
268 call the ao_wakeup function to wake AltOS tasks.
272 <title>__critical functions and statements</title>
274 SDCC has built-in support for suspending interrupts during
275 critical code. Functions marked as __critical will have
276 interrupts suspended for the whole period of
277 execution. Individual statements may also be marked as
278 __critical which blocks interrupts during the execution of
279 that statement. Keeping critical sections as short as
280 possible is key to ensuring that interrupts are handled as
287 <title>Task functions</title>
289 This chapter documents how to create, destroy and schedule AltOS tasks.
292 <title>ao_add_task</title>
295 ao_add_task(__xdata struct ao_task * task,
300 This initializes the statically allocated task structure,
301 assigns a name to it (not used for anything but the task
302 display), and the start address. It does not switch to the
303 new task. 'start' must not ever return; there is no place
308 <title>ao_exit</title>
314 This terminates the current task.
318 <title>ao_sleep</title>
321 ao_sleep(__xdata void *wchan)
324 This suspends the current task until 'wchan' is signaled
325 by ao_wakeup, or until the timeout, set by ao_alarm,
326 fires. If 'wchan' is signaled, ao_sleep returns 0, otherwise
327 it returns 1. This is the only way to switch to another task.
330 Because ao_wakeup wakes every task waiting on a particular
331 location, ao_sleep should be used in a loop that first
332 checks the desired condition, blocks in ao_sleep and then
333 rechecks until the condition is satisfied. If the
334 location may be signaled from an interrupt handler, the
335 code will need to block interrupts by using the __critical
336 label around the block of code. Here's a complete example:
338 __critical while (!ao_radio_done)
339 ao_sleep(&ao_radio_done);
344 <title>ao_wakeup</title>
347 ao_wakeup(__xdata void *wchan)
350 Wake all tasks blocked on 'wchan'. This makes them
351 available to be run again, but does not actually switch
352 to another task. Here's an example of using this:
354 if (RFIF & RFIF_IM_DONE) {
356 ao_wakeup(&ao_radio_done);
357 RFIF &= ~RFIF_IM_DONE;
360 Note that this need not be enclosed in __critical as the
361 ao_sleep block can only be run from normal mode, and so
362 this sequence can never be interrupted with execution of
367 <title>ao_alarm</title>
370 ao_alarm(uint16_t delay)
373 Schedules an alarm to fire in at least 'delay' ticks. If
374 the task is asleep when the alarm fires, it will wakeup
375 and ao_sleep will return 1.
377 ao_alarm(ao_packet_master_delay);
378 __critical while (!ao_radio_dma_done)
379 if (ao_sleep(&ao_radio_dma_done) != 0)
382 In this example, a timeout is set before waiting for
383 incoming radio data. If no data is received before the
384 timeout fires, ao_sleep will return 1 and then this code
385 will abort the radio receive operation.
389 <title>ao_wake_task</title>
392 ao_wake_task(__xdata struct ao_task *task)
395 Force a specific task to wake up, independent of which
396 'wchan' it is waiting for.
400 <title>ao_start_scheduler</title>
403 ao_start_scheduler(void)
406 This is called from 'main' when the system is all
407 initialized and ready to run. It will not return.
411 <title>ao_clock_init</title>
417 This turns on the external 48MHz clock then switches the
418 hardware to using it. This is required by many of the
419 internal devices like USB. It should be called by the
420 'main' function first, before initializing any of the
421 other devices in the system.
426 <title>Timer Functions</title>
428 AltOS sets up one of the cc1111 timers to run at 100Hz and
429 exposes this tick as the fundemental unit of time. At each
430 interrupt, AltOS increments the counter, and schedules any tasks
431 waiting for that time to pass, then fires off the ADC system to
432 collect current data readings. Doing this from the ISR ensures
433 that the ADC values are sampled at a regular rate, independent
434 of any scheduling jitter.
437 <title>ao_time</title>
443 Returns the current system tick count. Note that this is
444 only a 16 bit value, and so it wraps every 655.36 seconds.
448 <title>ao_delay</title>
451 ao_delay(uint16_t ticks);
454 Suspend the current task for at least 'ticks' clock units.
458 <title>ao_timer_set_adc_interval</title>
461 ao_timer_set_adc_interval(uint8_t interval);
464 This sets the number of ticks between ADC samples. If set
465 to 0, no ADC samples are generated. AltOS uses this to
466 slow down the ADC sampling rate to save power.
470 <title>ao_timer_init</title>
476 This turns on the 100Hz tick using the CC1111 timer 1. It
477 is required for any of the time-based functions to
478 work. It should be called by 'main' before ao_start_scheduler.
483 <title>AltOS Mutexes</title>
485 AltOS provides mutexes as a basic synchronization primitive. Each
486 mutexes is simply a byte of memory which holds 0 when the mutex
487 is free or the task id of the owning task when the mutex is
488 owned. Mutex calls are checked—attempting to acquire a mutex
489 already held by the current task or releasing a mutex not held
490 by the current task will both cause a panic.
493 <title>ao_mutex_get</title>
496 ao_mutex_get(__xdata uint8_t *mutex);
499 Acquires the specified mutex, blocking if the mutex is
500 owned by another task.
504 <title>ao_mutex_put</title>
507 ao_mutex_put(__xdata uint8_t *mutex);
510 Releases the specified mutex, waking up all tasks waiting
516 <title>CC1111 DMA engine</title>
518 The CC1111 contains a useful bit of extra hardware in the form
519 of five programmable DMA engines. They can be configured to copy
520 data in memory, or between memory and devices (or even between
521 two devices). AltOS exposes a general interface to this hardware
522 and uses it to handle radio and SPI data.
525 Code using a DMA engine should allocate one at startup
526 time. There is no provision to free them, and if you run out,
527 AltOS will simply panic.
530 During operation, the DMA engine is initialized with the
531 transfer parameters. Then it is started, at which point it
532 awaits a suitable event to start copying data. When copying data
533 from hardware to memory, that trigger event is supplied by the
534 hardware device. When copying data from memory to hardware, the
535 transfer is usually initiated by software.
538 <title>ao_dma_alloc</title>
541 ao_dma_alloc(__xdata uint8_t *done)
544 Allocates a DMA engine, returning the identifier. Whenever
545 this DMA engine completes a transfer. 'done' is cleared
546 when the DMA is started, and then receives the
547 AO_DMA_DONE bit on a successful transfer or the
548 AO_DMA_ABORTED bit if ao_dma_abort was called. Note that
549 it is possible to get both bits if the transfer was
550 aborted after it had finished.
554 <title>ao_dma_set_transfer</title>
557 ao_dma_set_transfer(uint8_t id,
558 void __xdata *srcaddr,
559 void __xdata *dstaddr,
565 Initializes the specified dma engine to copy data
566 from 'srcaddr' to 'dstaddr' for 'count' units. cfg0 and
567 cfg1 are values directly out of the CC1111 documentation
568 and tell the DMA engine what the transfer unit size,
569 direction and step are.
573 <title>ao_dma_start</title>
576 ao_dma_start(uint8_t id);
579 Arm the specified DMA engine and await a signal from
580 either hardware or software to start transferring data.
584 <title>ao_dma_trigger</title>
587 ao_dma_trigger(uint8_t id)
590 Trigger the specified DMA engine to start copying data.
594 <title>ao_dma_abort</title>
597 ao_dma_abort(uint8_t id)
600 Terminate any in-progress DMA transation, marking its
601 'done' variable with the AO_DMA_ABORTED bit.
606 <title>SDCC Stdio interface</title>
608 AltOS offers a stdio interface over both USB and the RF packet
609 link. This provides for control of the device localy or
610 remotely. This is hooked up to the stdio functions in SDCC by
611 providing the standard putchar/getchar/flush functions. These
612 automatically multiplex the two available communication
613 channels; output is always delivered to the channel which
614 provided the most recent input.
617 <title>putchar</title>
623 Delivers a single character to the current console
628 <title>getchar</title>
634 Reads a single character from any of the available
635 console devices. The current console device is set to
636 that which delivered this character. This blocks until
637 a character is available.
647 Flushes the current console device output buffer. Any
648 pending characters will be delivered to the target device.
652 <title>ao_add_stdio</title>
655 ao_add_stdio(char (*pollchar)(void),
656 void (*putchar)(char),
660 This adds another console device to the available
664 'pollchar' returns either an available character or
665 AO_READ_AGAIN if none is available. Significantly, it does
666 not block. The device driver must set 'ao_stdin_ready' to
667 1 and call ao_wakeup(&ao_stdin_ready) when it receives
668 input to tell getchar that more data is available, at
669 which point 'pollchar' will be called again.
672 'putchar' queues a character for output, flushing if the output buffer is
673 full. It may block in this case.
676 'flush' forces the output buffer to be flushed. It may
677 block until the buffer is delivered, but it is not
683 <title>Command line interface</title>
685 AltOS includes a simple command line parser which is hooked up
686 to the stdio interfaces permitting remote control of the device
687 over USB or the RF link as desired. Each command uses a single
688 character to invoke it, the remaining characters on the line are
689 available as parameters to the command.
692 <title>ao_cmd_register</title>
695 ao_cmd_register(__code struct ao_cmds *cmds)
698 This registers a set of commands with the command
699 parser. There is a fixed limit on the number of command
700 sets, the system will panic if too many are registered.
701 Each command is defined by a struct ao_cmds entry:
709 'cmd' is the character naming the command. 'func' is the
710 function to invoke and 'help' is a string displayed by the
711 '?' command. Syntax errors found while executing 'func'
712 should be indicated by modifying the global ao_cmd_status
713 variable with one of the following values:
716 <title>ao_cmd_success</title>
719 The command was parsed successfully. There is no
720 need to assign this value, it is the default.
725 <title>ao_cmd_lex_error</title>
728 A token in the line was invalid, such as a number
729 containing invalid characters. The low-level
730 lexing functions already assign this value as needed.
735 <title>ao_syntax_error</title>
738 The command line is invalid for some reason other
747 <title>ao_cmd_lex</title>
753 This gets the next character out of the command line
754 buffer and sticks it into ao_cmd_lex_c. At the end of the
755 line, ao_cmd_lex_c will get a newline ('\n') character.
759 <title>ao_cmd_put16</title>
762 ao_cmd_put16(uint16_t v);
765 Writes 'v' as four hexadecimal characters.
769 <title>ao_cmd_put8</title>
772 ao_cmd_put8(uint8_t v);
775 Writes 'v' as two hexadecimal characters.
779 <title>ao_cmd_white</title>
785 This skips whitespace by calling ao_cmd_lex while
786 ao_cmd_lex_c is either a space or tab. It does not skip
787 any characters if ao_cmd_lex_c already non-white.
791 <title>ao_cmd_hex</title>
797 This reads a 16-bit hexadecimal value from the command
798 line with optional leading whitespace. The resulting value
799 is stored in ao_cmd_lex_i;
803 <title>ao_cmd_decimal</title>
809 This reads a 32-bit decimal value from the command
810 line with optional leading whitespace. The resulting value
811 is stored in ao_cmd_lex_u32 and the low 16 bits are stored
816 <title>ao_match_word</title>
819 ao_match_word(__code char *word)
822 This checks to make sure that 'word' occurs on the command
823 line. It does not skip leading white space. If 'word' is
824 found, then 1 is returned. Otherwise, ao_cmd_status is set to
825 ao_cmd_syntax_error and 0 is returned.
829 <title>ao_cmd_init</title>
835 Initializes the command system, setting up the built-in
836 commands and adding a task to run the command processing
837 loop. It should be called by 'main' before ao_start_scheduler.
842 <title>CC1111 USB target device</title>
844 The CC1111 contains a full-speed USB target device. It can be
845 programmed to offer any kind of USB target, but to simplify
846 interactions with a variety of operating systems, AltOS provides
847 only a single target device profile, that of a USB modem which
848 has native drivers for Linux, Windows and Mac OS X. It would be
849 easy to change the code to provide an alternate target device if
853 To the rest of the system, the USB device looks like a simple
854 two-way byte stream. It can be hooked into the command line
855 interface if desired, offering control of the device over the
856 USB link. Alternatively, the functions can be accessed directly
857 to provide for USB-specific I/O.
860 <title>ao_usb_flush</title>
866 Flushes any pending USB output. This queues an 'IN' packet
867 to be delivered to the USB host if there is pending data,
868 or if the last IN packet was full to indicate to the host
869 that there isn't any more pending data available.
873 <title>ao_usb_putchar</title>
876 ao_usb_putchar(char c);
879 If there is a pending 'IN' packet awaiting delivery to the
880 host, this blocks until that has been fetched. Then, this
881 adds a byte to the pending IN packet for delivery to the
882 USB host. If the USB packet is full, this queues the 'IN'
887 <title>ao_usb_pollchar</title>
890 ao_usb_pollchar(void);
893 If there are no characters remaining in the last 'OUT'
894 packet received, this returns AO_READ_AGAIN. Otherwise, it
895 returns the next character, reporting to the host that it
896 is ready for more data when the last character is gone.
900 <title>ao_usb_getchar</title>
903 ao_usb_getchar(void);
906 This uses ao_pollchar to receive the next character,
907 blocking while ao_pollchar returns AO_READ_AGAIN.
911 <title>ao_usb_disable</title>
914 ao_usb_disable(void);
917 This turns off the USB controller. It will no longer
918 respond to host requests, nor return characters. Calling
919 any of the i/o routines while the USB device is disabled
920 is undefined, and likely to break things. Disabling the
921 USB device when not needed saves power.
924 Note that neither TeleDongle nor TeleMetrum are able to
925 signal to the USB host that they have disconnected, so
926 after disabling the USB device, it's likely that the cable
927 will need to be disconnected and reconnected before it
932 <title>ao_usb_enable</title>
938 This turns the USB controller on again after it has been
939 disabled. See the note above about needing to physically
940 remove and re-insert the cable to get the host to
941 re-initialize the USB link.
945 <title>ao_usb_init</title>
951 This turns the USB controller on, adds a task to handle
952 the control end point and adds the usb I/O functions to
953 the stdio system. Call this from main before
959 <title>CC1111 Serial peripheral</title>
961 The CC1111 provides two USART peripherals. AltOS uses one for
962 asynch serial data, generally to communicate with a GPS device,
963 and the other for a SPI bus. The UART is configured to operate
964 in 8-bits, no parity, 1 stop bit framing. The default
965 configuration has clock settings for 4800, 9600 and 57600 baud
966 operation. Additional speeds can be added by computing
967 appropriate clock values.
970 To prevent loss of data, AltOS provides receive and transmit
971 fifos of 32 characters each.
974 <title>ao_serial_getchar</title>
977 ao_serial_getchar(void);
980 Returns the next character from the receive fifo, blocking
981 until a character is received if the fifo is empty.
985 <title>ao_serial_putchar</title>
988 ao_serial_putchar(char c);
991 Adds a character to the transmit fifo, blocking if the
992 fifo is full. Starts transmitting characters.
996 <title>ao_serial_drain</title>
999 ao_serial_drain(void);
1002 Blocks until the transmit fifo is empty. Used internally
1003 when changing serial speeds.
1007 <title>ao_serial_set_speed</title>
1010 ao_serial_set_speed(uint8_t speed);
1013 Changes the serial baud rate to one of
1014 AO_SERIAL_SPEED_4800, AO_SERIAL_SPEED_9600 or
1015 AO_SERIAL_SPEED_57600. This first flushes the transmit
1016 fifo using ao_serial_drain.
1020 <title>ao_serial_init</title>
1023 ao_serial_init(void)
1026 Initializes the serial peripheral. Call this from 'main'
1027 before jumping to ao_start_scheduler. The default speed
1028 setting is AO_SERIAL_SPEED_4800.
1033 <title>CC1111 Radio peripheral</title>
1035 The CC1111 radio transceiver sends and receives digital packets
1036 with forward error correction and detection. The AltOS driver is
1037 fairly specific to the needs of the TeleMetrum and TeleDongle
1038 devices, using it for other tasks may require customization of
1039 the driver itself. There are three basic modes of operation:
1043 Telemetry mode. In this mode, TeleMetrum transmits telemetry
1044 frames at a fixed rate. The frames are of fixed size. This
1045 is strictly a one-way communication from TeleMetrum to
1051 Packet mode. In this mode, the radio is used to create a
1052 reliable duplex byte stream between TeleDongle and
1053 TeleMetrum. This is an asymmetrical protocol with
1054 TeleMetrum only transmitting in response to a packet sent
1055 from TeleDongle. Thus getting data from TeleMetrum to
1056 TeleDongle requires polling. The polling rate is adaptive,
1057 when no data has been received for a while, the rate slows
1058 down. The packets are checked at both ends and invalid
1062 On the TeleMetrum side, the packet link is hooked into the
1063 stdio mechanism, providing an alternate data path for the
1064 command processor. It is enabled when the unit boots up in
1068 On the TeleDongle side, the packet link is enabled with a
1069 command; data from the stdio package is forwarded over the
1070 packet link providing a connection from the USB command
1071 stream to the remote TeleMetrum device.
1076 Radio Direction Finding mode. In this mode, TeleMetrum
1077 constructs a special packet that sounds like an audio tone
1078 when received by a conventional narrow-band FM
1079 receiver. This is designed to provide a beacon to track
1080 the device when other location mechanisms fail.
1086 <title>ao_radio_set_telemetry</title>
1089 ao_radio_set_telemetry(void);
1092 Configures the radio to send or receive telemetry
1093 packets. This includes packet length, modulation scheme and
1094 other RF parameters. It does not include the base frequency
1095 or channel though. Those are set at the time of transmission
1096 or reception, in case the values are changed by the user.
1100 <title>ao_radio_set_packet</title>
1103 ao_radio_set_packet(void);
1106 Configures the radio to send or receive packet data. This
1107 includes packet length, modulation scheme and other RF
1108 parameters. It does not include the base frequency or
1109 channel though. Those are set at the time of transmission or
1110 reception, in case the values are changed by the user.
1114 <title>ao_radio_set_rdf</title>
1117 ao_radio_set_rdf(void);
1120 Configures the radio to send RDF 'packets'. An RDF 'packet'
1121 is a sequence of hex 0x55 bytes sent at a base bit rate of
1122 2kbps using a 5kHz deviation. All of the error correction
1123 and data whitening logic is turned off so that the resulting
1124 modulation is received as a 1kHz tone by a conventional 70cm
1129 <title>ao_radio_idle</title>
1132 ao_radio_idle(void);
1135 Sets the radio device to idle mode, waiting until it reaches
1136 that state. This will terminate any in-progress transmit or
1141 <title>ao_radio_get</title>
1147 Acquires the radio mutex and then configures the radio
1148 frequency using the global radio calibration and channel
1153 <title>ao_radio_put</title>
1159 Releases the radio mutex.
1163 <title>ao_radio_abort</title>
1166 ao_radio_abort(void);
1169 Aborts any transmission or reception process by aborting the
1170 associated DMA object and calling ao_radio_idle to terminate
1171 the radio operation.
1175 In telemetry mode, you can send or receive a telemetry
1176 packet. The data from receiving a packet also includes the RSSI
1177 and status values supplied by the receiver. These are added
1178 after the telemetry data.
1181 <title>ao_radio_send</title>
1184 ao_radio_send(__xdata struct ao_telemetry *telemetry);
1187 This sends the specific telemetry packet, waiting for the
1188 transmission to complete. The radio must have been set to
1189 telemetry mode. This function calls ao_radio_get() before
1190 sending, and ao_radio_put() afterwards, to correctly
1191 serialize access to the radio device.
1195 <title>ao_radio_recv</title>
1198 ao_radio_recv(__xdata struct ao_radio_recv *radio);
1201 This blocks waiting for a telemetry packet to be received.
1202 The radio must have been set to telemetry mode. This
1203 function calls ao_radio_get() before receiving, and
1204 ao_radio_put() afterwards, to correctly serialize access
1205 to the radio device. This returns non-zero if a packet was
1206 received, or zero if the operation was aborted (from some
1207 other task calling ao_radio_abort()).
1211 In radio direction finding mode, there's just one function to
1215 <title>ao_radio_rdf</title>
1218 ao_radio_rdf(int ms);
1221 This sends an RDF packet lasting for the specified amount
1222 of time. The maximum length is 1020 ms.
1226 Packet mode is asymmetrical and is configured at compile time
1227 for either master or slave mode (but not both). The basic I/O
1228 functions look the same at both ends, but the internals are
1229 different, along with the initialization steps.
1232 <title>ao_packet_putchar</title>
1235 ao_packet_putchar(char c);
1238 If the output queue is full, this first blocks waiting for
1239 that data to be delivered. Then, queues a character for
1240 packet transmission. On the master side, this will
1241 transmit a packet if the output buffer is full. On the
1242 slave side, any pending data will be sent the next time
1243 the master polls for data.
1247 <title>ao_packet_pollchar</title>
1250 ao_packet_pollchar(void);
1253 This returns a pending input character if available,
1254 otherwise returns AO_READ_AGAIN. On the master side, if
1255 this empties the buffer, it triggers a poll for more data.
1259 <title>ao_packet_slave_start</title>
1262 ao_packet_slave_start(void);
1265 This is available only on the slave side and starts a task
1266 to listen for packet data.
1270 <title>ao_packet_slave_stop</title>
1273 ao_packet_slave_stop(void);
1276 Disables the packet slave task, stopping the radio receiver.
1280 <title>ao_packet_slave_init</title>
1283 ao_packet_slave_init(void);
1286 Adds the packet stdio functions to the stdio package so
1287 that when packet slave mode is enabled, characters will
1288 get send and received through the stdio functions.
1292 <title>ao_packet_master_init</title>
1295 ao_packet_master_init(void);
1298 Adds the 'p' packet forward command to start packet mode.
projects / fw / altos / blob