Standard Library
Index
- Digital Inputs & Outputs
- Serial Interface
- Analog Inputs (ADC)
- Analog Outputs (PWM)
- TWI (I2C) Interface
- SPI interface
- Utility functions
- String functions
- System functions
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:
Identifier | Pin | Actual value | |
---|---|---|---|
PIN_B0 | B0 | 0x2301 | |
PIN_B1 | B1 | 0x2302 | |
PIN_B2 | B2 | 0x2304 | |
PIN_B3 | B3 | 0x2308 | |
PIN_B4 | B4 | 0x2310 | |
PIN_B5 | B5 | 0x2320 | |
PIN_C0 | C0 | 0x2601 | |
PIN_C1 | C1 | 0x2602 | |
PIN_C2 | C2 | 0x2604 | |
PIN_C3 | C3 | 0x2608 | |
PIN_C4 | C4 | 0x2610 | |
PIN_C5 | C5 | 0x2620 | |
PIN_D0 | D0 | 0x2901 | |
PIN_D1 | D1 | 0x2902 | |
PIN_D2 | D2 | 0x2904 | |
PIN_D3 | D3 | 0x2908 | |
PIN_D4 | D4 | 0x2910 | |
PIN_D5 | D5 | 0x2920 | |
PIN_D6 | D6 | 0x2940 | |
PIN_D7 | D7 | 0x2980 | |
*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.
Constant | Setting | Actual value |
---|---|---|
DEFAULT | 115200 bps,1 bit stop,No parity | 0x00000000 |
SERIAL_DEFAULT_SETTING | 115200 bps,1 bit stop,No parity | 0x10061802 |
SERIAL_BAU4800_8N1 | 4800 bps,1 bit stop,No parity | 0xCF061800 |
SERIAL_BAU9600_8N1 | 9600 bps,1 bit stop,No parity | 0x67061800 |
SERIAL_BAU14400_8N1 | 14400 bps,1 bit stop,No parity | 0x44061800 |
SERIAL_BAU19200_8N1 | 19200 bps,1 bit stop,No parity | 0x33061800 |
SERIAL_BAU28800_8N1 | 28800 bps,1 bit stop,No parity | 0x22061800 |
SERIAL_BAU38400_8N1 | 38400 bps,1 bit stop,No parity | 0x19061800 |
SERIAL_BAU57600_8N1 | 57600 bps,1 bit stop,No parity | 0x22061802 |
SERIAL_BAU76800_8N1 | 76800 bps,1 bit stop,No parity | 0x0C061800 |
SERIAL_BAU115200_8N1 | 115200 bps,1 bit stop,No parity | 0x10061802 |
*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.
Constant | Setting | Actual value |
---|---|---|
DEFAULT | 10 bit, 5V reference, 250KHz clock | 0x00000000 |
ADC_DEFAULT_SETTING | 10 bit, 5V reference, 250KHz clock | 0x00400086 |
ADC_10BIT_1V1_REF | 10 bit, internal 1.1V reference, 250KHz clock | 0x00C00086 |
ADC_10BIT_FAST | 10 bit, 5V reference, 1MHz clock | 0x00400084 |
ADC_8BIT | 8 bit, 5V reference, 250KHz clock | 0x00600086 |
ADC_8BIT_FAST | 8 bit, 5V reference, 1MHz clock | 0x00600084 |
ADC_8BIT_1V1_REF | 8 bit, Internal 1.1V reference, 250KHz clock | 0x00E00086 |
ADC_10BIT_EXT_REF | 10 bit, external reference (AREF pin), 250KHz clock | 0x00000086 |
ADC_10BIT_EXT_REF_FAST | 10 bit, external reference (AREF pin), 1MHz clock | 0x00000084 |
ADC_8BIT_EXT_REF | 8 bit, external reference (AREF pin), 250KHz clock | 0x00200086 |
ADC_8BIT_EXT_REF_FAST | 8 bit, external reference (AREF pin), 1MHz clock | 0x00200084 |
*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.
Identifier | Analog pin | Actual value |
---|---|---|
ADC_ON_PIN_C0 | input on pin C0 | 0 |
ADC_ON_PIN_C1 | input on pin C1 | 1 |
ADC_ON_PIN_C2 | input on pin C2 | 2 |
ADC_ON_PIN_C3 | input on pin C3 | 3 |
ADC_ON_PIN_C4 | input on pin C4 | 4 |
ADC_ON_PIN_C5 | input on pin C5 | 5 |
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.
Identifier | Analog pin | Actual value |
---|---|---|
PWM_ON_PIN_D6 | PWM on pin D6 | 1 |
PWM_ON_PIN_D5 | PWM on pin D5 | 2 |
PWM_ON_PIN_B1 | PWM on pin B1 | 3 |
PWM_ON_PIN_B2 | PWM on pin B2 | 4 |
PWM_ON_PIN_B3 | PWM on pin B3 | 5 |
PWM_ON_PIN_D3 | PWM on pin D3 | 6 |
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.
Identifier | Frequency | Actual value |
---|---|---|
PWM_FREQUENCY_62K | 62.5KHz | 1 |
PWM_FREQUENCY_7K8 | 7.8KHz | 2 |
PWM_FREQUENCY_976 | 976Hz | 3 |
PWM_FREQUENCY_224 | 244Hz | 4 |
PWM_FREQUENCY_61 | 61Hz | 5 |
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.
Identifier | Setting | Actual value |
---|---|---|
DEFAULT | Master mode, 100KHz bitrate | 0x00000000 |
TWI_DEFAULT_SETTING | Master mode, 100KHz bitrate | 0x00000448 |
TWI_MASTER_100K | Master mode, 100KHz bitrate | 0x00000448 |
TWI_MASTER_400K | Master mode, 400KHz bitrate | 0x0000040C |
*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.
Identifier | Setting | Actual value |
---|---|---|
DEFAULT | Master mode 0, 250KHz bitrate | 0x00000000 |
SPI_DEFAULT_SETTING | Master mode 0, 250KHz bitrate | 0x0000522C |
SPI_MASTER_MODE0_125K | Master mode 0, 125KHz bitrate | 0x0000532C |
SPI_MASTER_MODE0_250K | Master mode 0, 250KHz bitrate | 0x0000522C |
SPI_MASTER_MODE0_1M | Master mode 0, 1MHz bitrate | 0x0000512C |
SPI_MASTER_MODE0_4M | Master mode 0, 4MHz bitrate | 0x0000502C |
*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.
Identifier | Sleep mode | Actual value |
---|---|---|
IDLE | CPU IDLE | 0x00 |
ADC_NOISE_REDUCTION | Used to reduce noise from CPU while ADC runing | 0x02 |
POWER_DOWN | Deep power down | 0x04 |
POWER_SAVE | Like POWER_DOWN but some part is left running | 0x06 |
STANDBY | Should only used when clock source is from crystal | 0x0C |
EXT_STANDBY | Similar to STANDBY | 0x0E |
*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.