AltOS

These primitive operations provide the abstraction needed to run the multi-tasking framework while providing reliable interrupt delivery.

These functions provide an abstract interface to configure and manipulate GPIO pins.

The data/xdata/__code memory spaces below were completely separate in the original 8051 design. In the cc1111, this isn’t true—they all live in a single unified 64kB address space, and so it’s possible to convert any address into a unique 16-bit address. SDCC doesn’t know this, and so a 'global' address to SDCC consumes 3 bytes of memory, 1 byte as a tag indicating the memory space and 2 bytes of offset within that space. AltOS avoids these 3-byte addresses as much as possible; using them involves a function call per byte access. The result is that nearly every variable declaration is decorated with a memory space identifier which clutters the code but makes the resulting code far smaller and more efficient.

Because stack addressing is expensive, and stack space limited, the default function call declaration in SDCC allocates all parameters and local variables in static global memory. Just like fortran. This makes these functions non-reentrant, and also consume space for parameters and locals even when they are not running. The benefit is smaller code and faster execution.

This initializes the statically allocated task structure, assigns a name to it (not used for anything but the task display), and the start address. It does not switch to the new task. 'start' must not ever return; there is no place to return to.

This terminates the current task.

This suspends the current task until 'wchan' is signaled by ao_wakeup, or until the timeout, set by ao_alarm, fires. If 'wchan' is signaled, ao_sleep returns 0, otherwise it returns 1. This is the only way to switch to another task.

Because ao_wakeup wakes every task waiting on a particular location, ao_sleep should be used in a loop that first checks the desired condition, blocks in ao_sleep and then rechecks until the condition is satisfied. If the location may be signaled from an interrupt handler, the code will need to block interrupts around the block of code. Here’s a complete example:

Wake all tasks blocked on 'wchan'. This makes them available to be run again, but does not actually switch to another task. Here’s an example of using this:

Note that this need not block interrupts as the ao_sleep block can only be run from normal mode, and so this sequence can never be interrupted with execution of the other sequence.

Schedules an alarm to fire in at least 'delay' ticks. If the task is asleep when the alarm fires, it will wakeup and ao_sleep will return 1. ao_clear_alarm resets any pending alarm so that it doesn’t fire at some arbitrary point in the future.

In this example, a timeout is set before waiting for incoming radio data. If no data is received before the timeout fires, ao_sleep will return 1 and then this code will abort the radio receive operation.

This is called from 'main' when the system is all initialized and ready to run. It will not return.

This initializes the main CPU clock and switches to it.

Returns the current system tick count. Note that this is only a 16 bit value, and so it wraps every 655.36 seconds.

Suspend the current task for at least 'ticks' clock units.

This sets the number of ticks between ADC samples. If set to 0, no ADC samples are generated. AltOS uses this to slow down the ADC sampling rate to save power.

This turns on the 100Hz tick. It is required for any of the time-based functions to work. It should be called by 'main' before ao_start_scheduler.

Acquires the specified mutex, blocking if the mutex is owned by another task.

Releases the specified mutex, waking up all tasks waiting for it.

Delivers a single character to the current console device.

Reads a single character from any of the available console devices. The current console device is set to that which delivered this character. This blocks until a character is available.

Flushes the current console device output buffer. Any pending characters will be delivered to the target device.

This adds another console device to the available list.

'pollchar' returns either an available character or AO_READ_AGAIN if none is available. Significantly, it does not block. The device driver must set 'ao_stdin_ready' to 1 and call ao_wakeup(&ao_stdin_ready) when it receives input to tell getchar that more data is available, at which point 'pollchar' will be called again.

'putchar' queues a character for output, flushing if the output buffer is full. It may block in this case.

'flush' forces the output buffer to be flushed. It may block until the buffer is delivered, but it is not required to do so.

This registers a set of commands with the command parser. There is a fixed limit on the number of command sets, the system will panic if too many are registered. Each command is defined by a struct ao_cmds entry:

'cmd' is the character naming the command. 'func' is the function to invoke and 'help' is a string displayed by the '?' command. Syntax errors found while executing 'func' should be indicated by modifying the global ao_cmd_status variable with one of the following values:

This gets the next character out of the command line buffer and sticks it into ao_cmd_lex_c. At the end of the line, ao_cmd_lex_c will get a newline ('\n') character.

Writes 'v' as four hexadecimal characters.

Writes 'v' as two hexadecimal characters.

This skips whitespace by calling ao_cmd_lex while ao_cmd_lex_c is either a space or tab. It does not skip any characters if ao_cmd_lex_c already non-white.

This reads a 16-bit hexadecimal value from the command line with optional leading whitespace. The resulting value is stored in ao_cmd_lex_i;

This reads a 32-bit decimal value from the command line with optional leading whitespace. The resulting value is stored in ao_cmd_lex_u32 and the low 16 bits are stored in ao_cmd_lex_i;

This checks to make sure that 'word' occurs on the command line. It does not skip leading white space. If 'word' is found, then 1 is returned. Otherwise, ao_cmd_status is set to ao_cmd_syntax_error and 0 is returned.

Initializes the command system, setting up the built-in commands and adding a task to run the command processing loop. It should be called by 'main' before ao_start_scheduler.

Flushes any pending USB output. This queues an 'IN' packet to be delivered to the USB host if there is pending data, or if the last IN packet was full to indicate to the host that there isn’t any more pending data available.

If there is a pending 'IN' packet awaiting delivery to the host, this blocks until that has been fetched. Then, this adds a byte to the pending IN packet for delivery to the USB host. If the USB packet is full, this queues the 'IN' packet for delivery.

If there are no characters remaining in the last 'OUT' packet received, this returns AO_READ_AGAIN. Otherwise, it returns the next character, reporting to the host that it is ready for more data when the last character is gone.

This uses ao_pollchar to receive the next character, blocking while ao_pollchar returns AO_READ_AGAIN.

This turns off the USB controller. It will no longer respond to host requests, nor return characters. Calling any of the i/o routines while the USB device is disabled is undefined, and likely to break things. Disabling the USB device when not needed saves power.

Note that neither TeleDongle v0.2 nor TeleMetrum v1 are able to signal to the USB host that they have disconnected, so after disabling the USB device, it’s likely that the cable will need to be disconnected and reconnected before it will work again.

This turns the USB controller on again after it has been disabled. See the note above about needing to physically remove and re-insert the cable to get the host to re-initialize the USB link.

This turns the USB controller on, adds a task to handle the control end point and adds the usb I/O functions to the stdio system. Call this from main before ao_start_scheduler.

Returns the next character from the receive fifo, blocking until a character is received if the fifo is empty.

Adds a character to the transmit fifo, blocking if the fifo is full. Starts transmitting characters.

Blocks until the transmit fifo is empty. Used internally when changing serial speeds.

Changes the serial baud rate to one of AO_SERIAL_SPEED_4800, AO_SERIAL_SPEED_9600 or AO_SERIAL_SPEED_57600. This first flushes the transmit fifo using ao_serial_drain.

Initializes the serial peripheral. Call this from 'main' before jumping to ao_start_scheduler. The default speed setting is AO_SERIAL_SPEED_4800.

The CC1111, CC1120 and CC1200 radio transceiver sends and receives digital packets with forward error correction and detection. The AltOS driver is fairly specific to the needs of the TeleMetrum and TeleDongle devices, using it for other tasks may require customization of the driver itself. There are three basic modes of operation:

On the TeleMetrum side, the packet link is hooked into the stdio mechanism, providing an alternate data path for the command processor. It is enabled when the unit boots up in 'idle' mode.

On the TeleDongle side, the packet link is enabled with a command; data from the stdio package is forwarded over the packet link providing a connection from the USB command stream to the remote TeleMetrum device.

Configures the radio to send or receive telemetry packets. This includes packet length, modulation scheme and other RF parameters. It does not include the base frequency or channel though. Those are set at the time of transmission or reception, in case the values are changed by the user.

Configures the radio to send or receive packet data. This includes packet length, modulation scheme and other RF parameters. It does not include the base frequency or channel though. Those are set at the time of transmission or reception, in case the values are changed by the user.

Configures the radio to send RDF 'packets'. An RDF 'packet' is a sequence of hex 0x55 bytes sent at a base bit rate of 2kbps using a 5kHz deviation. All of the error correction and data whitening logic is turned off so that the resulting modulation is received as a 1kHz tone by a conventional 70cm FM audio receiver.

Sets the radio device to idle mode, waiting until it reaches that state. This will terminate any in-progress transmit or receive operation.

Acquires the radio mutex and then configures the radio frequency using the global radio calibration and channel values.

Releases the radio mutex.

Aborts any transmission or reception process by aborting the associated DMA object and calling ao_radio_idle to terminate the radio operation.

In telemetry mode, you can send or receive a telemetry packet. The data from receiving a packet also includes the RSSI and status values supplied by the receiver. These are added after the telemetry data.

In radio direction finding mode, there’s just one function to use

Packet mode is asymmetrical and is configured at compile time for either master or slave mode (but not both). The basic I/O functions look the same at both ends, but the internals are different, along with the initialization steps.