Standard Library

Index

1. Digital Inputs & Output (I/O)

set_pin_mode(pin_id,direction);

Use this function to set up a digital I/O pin. Note that pin_id must be one of the identifiers in the table below, other values will not work. For direction, value 0 or "INPUT" will make the pin input, value "OUTPUT" or any value different than 0 will make it output.

set_pin(pin_id);

clear_pin(pin_id);

The two functions make given output pin high or low respectively. pin_id must be one of the identifiers in the table below, other values will not work.

toggle_pin(pin_id);

Toggle the current state of a pin. If a pin is low("0"), this function will make it high("1") and if the pin is high, this function will make it low.

read_pin(pin_id);

Read the current status of a pin. This function will return 1 if the pin is high and 0 if the pin is low. pin_id must be one of the identifiers in the table below, other values will not work.

pin_is_high(pin_id);

pin_is_low(pin_id);

The two functions above check if an input pin is high or low. These are used in condition for convenience. pin_id must be one of the identifiers in the table below, other values will not work.

shift_out(SCK_pin,SDA_pin,data);

Shift 1 byte out on given IO pin. Data bits will be clocked by SCK pin, on raising edges. Data is sent MSB first at fixed 500 KHz (CPU clock/32). SCK and SDA pins must be set as output before calling this function. The format of data is compatible with SPI mode 0.

shift_in(SCK_pin,SDA_pin);

Shift 1 byte in on given IO pins. This function will generate clock signal on pin SCK and read in each bit from SDA pin at the falling edges of clock signal. Data is shifted MSB first at fixed clock rate 500 KHz (CPU clock/32). This data format is compatible with SPI mode 0. SCK pin must be output and SDA pin must be input before calling this function.

pulse_out(pin,width);

Send 1 pulse from an output pin. Pulse width is given by input width in microsecond. The pin must be made output before calling this function. If the pin is currently low, a positive pulse will be sent. If the pin is currently high, a negative pulse will be sent.

pulse_in(pin,timeout);

Measure the width of a pulse coming to input pin. Input timeout is the total time of the entire capturing process. This function will detect 2 edges of a pulse and return the time between them. Time values are in microsecond. Value for timeout and the pulse width returned are long type (up to 4.29 billion microsecond).

pin_id Table:

IdentifierPinActual value
PIN_B0B00x2301
PIN_B1B10x2302
PIN_B2B20x2304
PIN_B3B30x2308
PIN_B4B40x2310
PIN_B5B50x2320
PIN_C0C00x2601
PIN_C1C10x2602
PIN_C2C20x2604
PIN_C3C30x2608
PIN_C4C40x2610
PIN_C5C50x2620
PIN_D0D00x2901
PIN_D1D10x2902
PIN_D2D20x2904
PIN_D3D30x2908
PIN_D4D40x2910
PIN_D5D50x2920
PIN_D6D60x2940
PIN_D7D70x2980
*For actual values of these identifiers, the high byte is base address of the pin and low byte is the pin mask.

ping(trigger_pin,echo_pin);

This function is designed to work with Ultrasonic distance sensor. It returns the number of microsecond of total ultrasound fly-time. Divide that by two and then multiply with the speed of sound (~345 m/s) to get the distance. The maximum time of fly is 65535 us. Function returns 0xFFFF (65535) if no echo after the maximum time.

2. Serial Interface

setup_serial(setting);

Initialize Serial interface according to the input setting. This function must be executed before Serial interface can be used. Setting value must be zero or one of the constants in the table below, other values may not work.

ConstantSettingActual value
DEFAULT115200 bps,1 bit stop,No parity0x00000000
SERIAL_DEFAULT_SETTING115200 bps,1 bit stop,No parity0x10061802
SERIAL_BAU4800_8N14800 bps,1 bit stop,No parity0xCF061800
SERIAL_BAU9600_8N19600 bps,1 bit stop,No parity0x67061800
SERIAL_BAU14400_8N114400 bps,1 bit stop,No parity0x44061800
SERIAL_BAU19200_8N119200 bps,1 bit stop,No parity0x33061800
SERIAL_BAU28800_8N128800 bps,1 bit stop,No parity0x22061800
SERIAL_BAU38400_8N138400 bps,1 bit stop,No parity0x19061800
SERIAL_BAU57600_8N157600 bps,1 bit stop,No parity0x22061802
SERIAL_BAU76800_8N176800 bps,1 bit stop,No parity0x0C061800
SERIAL_BAU115200_8N1115200 bps,1 bit stop,No parity0x10061802
*For actual values of these identifiers, the highest byte is baurate divider, 3 lower bytes are control registers C,B,A respectively.

serial_message("message");

Send a message over Serial Interface. The message must be a constant string in a quote or an array of char variables ending with zero value;

serial_send_byte(data);

Send a byte through Serial interface. If there was a byte not yet finished sending out, the function will wait. Otherwise, data will be written to transmit buffer and function will return immediately. Data input must be one byte (char). If more than one byte is given (int or long), only the least significant byte (LSB) will be sent.

serial_get_byte();

Get a byte from Serial interface. If a byte was received, function will return immediately with data, otherwise, function will wait and won't return until a byte is received. Data returned is one byte, char type.

serial_any_data();

Check if there is any byte has been received by Serial Interface. The function will return 1 if there is at least 1 byte received, 0 otherwise. Function returns immediately.

serial_print_int(int_num);

serial_print_long(long_num);

Translate an integer to printable characters (ASCII) and send them over serial interface. The first function used for small and medium numbers (char and int), the second one is used for long integers as well as other smaller ones

serial_print_hex8(char_num);

serial_print_hex16(int_num);

serial_print_hex32(long_num);

Translate a value to printable characters (ASCII) in hexadecimal format and send them over serial interface.

3. Analog inputs

setup_ADC(setting);

Start Analog to Digital Converter with the given setting. This function must be called before analog inputs can be read. Settings values must be zero or one of table below, other values may not work.

ConstantSettingActual value
DEFAULT10 bit, 5V reference, 250KHz clock0x00000000
ADC_DEFAULT_SETTING10 bit, 5V reference, 250KHz clock0x00400086
ADC_10BIT_1V1_REF10 bit, internal 1.1V reference, 250KHz clock0x00C00086
ADC_10BIT_FAST10 bit, 5V reference, 1MHz clock0x00400084
ADC_8BIT8 bit, 5V reference, 250KHz clock0x00600086
ADC_8BIT_FAST8 bit, 5V reference, 1MHz clock0x00600084
ADC_8BIT_1V1_REF8 bit, Internal 1.1V reference, 250KHz clock0x00E00086
ADC_10BIT_EXT_REF10 bit, external reference (AREF pin), 250KHz clock0x00000086
ADC_10BIT_EXT_REF_FAST10 bit, external reference (AREF pin), 1MHz clock0x00000084
ADC_8BIT_EXT_REF8 bit, external reference (AREF pin), 250KHz clock0x00200086
ADC_8BIT_EXT_REF_FAST8 bit, external reference (AREF pin), 1MHz clock0x00200084
*For actual values of these identifiers, the lowest byte is value of control register, the third from right is MUX register

read_analog_input(input_number);

Perform one Analog to Digital conversation (measuring the voltage) on the analog input specified by input_number. It can be any of number 0,1,2,3,4,5 or one of the indentifiers in the table below.

IdentifierAnalog pinActual value
ADC_ON_PIN_C0input on pin C00
ADC_ON_PIN_C1input on pin C11
ADC_ON_PIN_C2input on pin C22
ADC_ON_PIN_C3input on pin C33
ADC_ON_PIN_C4input on pin C44
ADC_ON_PIN_C5input on pin C55

read_analog_input_8b(input_number);

Similar to function above but used for 8bit mode

4. Analog Outputs (PWM)

setup_PWM(channel);

Enable PWM channel specified by channel value. The pin will automatically set as output and the initial PWM value is 0. Channel input must be one of the values in table below, other values will be ignored.

IdentifierAnalog pinActual value
PWM_ON_PIN_D6PWM on pin D61
PWM_ON_PIN_D5PWM on pin D52
PWM_ON_PIN_B1PWM on pin B13
PWM_ON_PIN_B2PWM on pin B24
PWM_ON_PIN_B3PWM on pin B35
PWM_ON_PIN_D3PWM on pin D36

set_PWM(channel,value);

Write a value to PWM channel. These values range from 0 to 255 corresponding to 0V to 5V. Input channel must be one of the values in table above.

change_PWM_frequency(channel, freq);

The default frequency of all PWM channels is 62.5 KHz. This function can be used to change that to lower frequencies. Note that PWM channels come in pair, changing frequency of one channel, the other on in pair will change as well. freq input must be one in the table below.

IdentifierFrequencyActual value
PWM_FREQUENCY_62K62.5KHz1
PWM_FREQUENCY_7K87.8KHz2
PWM_FREQUENCY_976976Hz3
PWM_FREQUENCY_224244Hz4
PWM_FREQUENCY_6161Hz5
PWMs on pin B1 and B2 are one pair, D5 and D6 are one pair,B3 and D3 are one pair.

5. TWI interface

setup_TWI(setting);

Initialize TWI interface. Setting input must be zero or one of the values in table below, other values may not work. This function must be called before using TWI interface to transfer data.

IdentifierSettingActual value
DEFAULTMaster mode, 100KHz bitrate0x00000000
TWI_DEFAULT_SETTINGMaster mode, 100KHz bitrate0x00000448
TWI_MASTER_100KMaster mode, 100KHz bitrate0x00000448
TWI_MASTER_400KMaster mode, 400KHz bitrate0x0000040C
*For actual values, the lowest byte is bitrate divider value, the next byte is control register value.

TWI_write(address, data_ptr, count);

Send one or more byte to TWI slave at given address. Note that bit 0 of input address will be ignored (internally set/clear by this function to indicated read/write). data_ptr is a pointer pointing to data to be sent. count is the number of byte to be sent. Function returns 1 if succeeded, 0 if failed.

TWI_read(address, data_buffer_ptr, count);

Read one or more byte from TWI slave at the given address then write data to buffer pointed by data_buffer_ptr. count is the number of byte to be read. Function returns 1 if succeeded, 0 if failed.

6. SPI interface

setup_SPI(setting);

Setup SPI interface with given setting. Setting values can be one in the table below. Pin B2 is automatically set as output and must not be changed to input.

IdentifierSettingActual value
DEFAULTMaster mode 0, 250KHz bitrate0x00000000
SPI_DEFAULT_SETTINGMaster mode 0, 250KHz bitrate0x0000522C
SPI_MASTER_MODE0_125KMaster mode 0, 125KHz bitrate0x0000532C
SPI_MASTER_MODE0_250KMaster mode 0, 250KHz bitrate0x0000522C
SPI_MASTER_MODE0_1MMaster mode 0, 1MHz bitrate0x0000512C
SPI_MASTER_MODE0_4MMaster mode 0, 4MHz bitrate0x0000502C
*For actual values, the lowest byte is I/O pins mask, the next bytes are control and status register values.

SPI_transfer(data);

Exchange data with slave device. The select pin of corresponding slave device must be set low (using clear_pin()) before execute this function.

7. Utility functions

delay_ms(int_value);

This function will do nothing and return after int_value millisecond(s). Note: the function counts number of CPU cycles to measure time, if there is a background task (interrupts) while it running, the measurement will be incorrect. TimeStamp library has a similar function that can be used.

delay_us(int_value);

Similar to function above except delay time is in microsecond. Maximum delay period is 65535 us.

read_EEPROM(address);

write_EEPROM(address,data);

Read or Write data in EEPROM memory inside of CPU. There are 1024 bytes of non-volatile memory can be used. Read function returns one byte at a time, write function will write one byte to given address (0-1023). If address is higher than 1023, only 10 lower bits are used. Therefore, address 1024 will be mapped to address 0, 1025 is mapped to 1 and so on.

sprint_int(buffer,int_value);

sprint_long(buffer, long_value);

sprint_hex16(buffer, value);

sprint_hex32(buffer, value);

Convert a value to printable string (ASCII) and write result to given buffer pointer(software print). The buffer must be large enough to hold result. Every output string will end with zero (0x00).

isqrt(value);

Return square root of an integer (int). Value is rounded to closest number.

random();

random_int();

random_long();

Generate a random number. Output values range from 0 to 255 for the first function, 0-65535 for the second one and 0-4294967295 for the third one. These functions require ADC set up before they can work, if not, these functions will not return. Random numbers are generated based on the noise from two unconnected ADC channels of Ansteron Board's CPU (ADC 6 and 7).

copy_mem(des,src,length);

Copy length number of byte from src to des.

8. String functions

string_length(str);

Returns the number of characters in a string. The maximum string length is 65535 characters.

string_compare(str1,str2);

Compares two strings, returns 1 if they match, 0 if they don't.

string_to_upper(str);

Convert all letters in a string to upper case. Only 24 letters of the alphabet are converted, numbers and other characters are left as is.

string_to_lower(str);

Convert all letters in a string to lower case. Only 24 letters of the alphabet are converted, numbers and other characters are left as is.

string_copy(des,src);

Copy a string from src to des. Note that buffer for destination string must be large enough to hold result. Function returns number of characters (byte) were copied.

find_string(str1, pattern);

Find the position in str1 where pattern first occurs. For example, string is "String Library" and pattern is "Lib", the return value will be 7. Character at position number 7 (counting starts from 0) is where the pattern first occurs. Function returns 65535 (0xFFFF) if the pattern was not found.

string_is_number(str);

Check if a string is qualified to be converted to integer. Use this to check the string before passing to function below.

string_to_int(str,int_ptr);

Convert a string to interger number if possible. Function returns 1 if success and 0 if false. On a successful conversation, data will be written to location at int_ptr, a pointer to an int variable.

9. System functions

system_enable_interrupt();

Allow all enabled interrupts to be served. This function is equivalent to SEI instruction and must be issued to allow any interrupt to be served.

system_disable_interrupt();

Disallow CPU to serve any interrupt. This function is equivalent to CLI instruction.

system_sleep(mode);

Enter sleep mode with given sleep mode value. Mode must be one of the values in the table below. An interrupt will wake the CPU up from sleep.

IdentifierSleep modeActual value
IDLECPU IDLE0x00
ADC_NOISE_REDUCTIONUsed to reduce noise from CPU while ADC runing0x02
POWER_DOWNDeep power down0x04
POWER_SAVELike POWER_DOWN but some part is left running0x06
STANDBYShould only used when clock source is from crystal0x0C
EXT_STANDBYSimilar to STANDBY0x0E
*These are values for sleep control register, see datasheet of ATMEGA328P for more details.

system_reset_watchdog();

Reset the watchdog counter, this function is equivalent to WDR instruction.

system_read_program_memory(offset);

Read a byte from program memory starting from the end of program code. This function is used to read data from attachment file that was added to the end of program code. If function system_indirect_call_function() is also used by an interrupt in the same program, interrupts should be disabled before calling this function to avoid data error.

system_indirect_call_function(function_address);

Indirectly call a function at given address. Be careful when using this function, incorrect address may cause unintended behaviors of the CPU. To get address of a function, use operator "&" in front.

set_CPU_clock(clock);

Set CPU internal clock divider, values range from 0 to 8 corresponding to 1,2,4,8,..256 cycles. Constants CPU_16MHz, CPU_8MHz, CPU_4MHz,...,CPU_62KHz can also be used.

get_CPU_clock();

Retrieve current CPU clock divider.