MEAM.Design - SAAST - M2 Custom Function Library

Here you will find a library of custom functions to provide easy access to many of the lower-level functions of the m2 and mX. Installation instructions can be found near the bottom of the page.

Provided Constants and Functions


Useful Constants:

  TRUE 1
FALSE 0
OFF 0
ON 1
TOGGLE 2
B0 ... F7 port pins


Initialization:

  m_init( ) disable JTAG and set the clock speed to 16MHz
m_disableJTAG( ) disable the JTAG functionality to provide access to F4-F7 pins
m_clockdivide(n) reduce the system clock by 2^n for n=0 to 8 (the default is 0, which provides a 16MHz clock)


Bit Manipulation:

  set(register,n) sets the n-th bit of register
clear(register,n) clears the n-th bit of register
toggle(register,n) toggles the n-th bit of register
check(register,n) returns the state of the n-th bit of register


Delay:

  m_wait(ms) delay the microcontroller for an integer number of milliseconds (assumes a 16 MHz system clock, max 65,535)


Onboard LEDs:

  m_red(state) set state to either ON, OFF, or TOGGLE to change the red onboard LED
m_green(state) set state to either ON, OFF, or TOGGLE to change the green onboard LED


Digital Input/Output

  m_gpio_out(channel, state) set the state of the specified digital output channel (B0 ... F7) to either ON or OFF
x = m_gpio_in(channel) read the state of the specified digital input channel (B0 ... F7), will return either 0 or 1


Analog Inputs

  x = m_adc(channel) read the value of the specified analog input channel (subset of B0 ... F7), where result will be between 0 and 1023 corresponding to 0V to 5V. See here to find out which pins can be used for analog inputs.


PWM Outputs

  x = m_pwm_timer(timer, freq) configure the PWM timer (0, 1, 3, or 4) to a floating-point frequency in Hertz. Will return 0 if error.
x = m_pwm_output(timer, channel, state) connect (state=ON) or disconnect (state=OFF) a PWM timer (0, 1, 3, or 4) to an output (timer 0, channel 1 = D0); (timer 1, channel 1 = B6, channel 2 = B7); (timer 3, channel 1 = C6); (timer 4, channel 1 = C7, channel 2 = B5, channel 3 = D7). Will return 0 if error.
x = m_pwm_duty(timer, channel, duty) set the floating point (0.0 to 100.0) duty cycle for a timer channel: (timer 0, channel 1 = D0); (timer 1, channel 1 = B6, channel 2 = B7); (timer 3, channel 1 = C6); (timer 4, channel 1 = C7, channel 2 = B5, channel 3 = D7). Will return 0 if error.


mBUS Communications

  m_bus_init( ) initialize the m2 data bus, which uses pins D0-D2 and is available through the 5-pin end header. When new data is available from a slave, the INT2_vect interrupt will be triggered, and must be handled accordingly.
x = m_read_register(addr, reg) retrieve a single byte (x) from slave device addr, register reg.


RF Wireless Communications

  x = m_rf_open(channel, RXaddress, packet_length) configure the RF subsystem on the mBUS to listen to a desired address (0x00 to 0xFF) over a wireless channel (1-32, TX/RX must match) with a specified packet length (1-32, TX/RX must match).
x = m_rf_read(buffer, packet_length) retrieve packet_length bytes from the receive buffer into buffer.
x = m_rf_send(TXaddress, buffer, packet_length) send the message contained in buffer of packet_length (1-32, TX/RX must match) bytes to an specified address (0x00 to 0xFF).


USB Communications

  m_usb_init( ) initialize the USB subsystem and attempt to connect to a computer
x = m_usb_isconnected( ) confirm that the USB port is connected to a computer.
x = m_usb_rx_available( ) returns the number of bytes (up to 255) in the receive buffer
x = m_usb_rx_char( ) retrieve the oldest byte from the receive buffer
m_usb_rx_flush( ) flush the receive buffer
m_usb_tx_char(x) place a single byte into the TX buffer and transmit as a character
m_usb_tx_hex(x) place a 16-bit unsigned int into the TX buffer, send as four hex-valued characters
m_usb_tx_int(x) place a 16-bit signed int into the TX buffer, send a decimal characters
m_usb_tx_uint(x) place a 16-bit unsigned int into the TX buffer, send a decimal characters
m_usb_tx_long(x) place a 32-bit signed long into the TX buffer, send a decimal characters
m_usb_tx_ulong(x) place a 32-bit unsigned int into the TX buffer, send a decimal characters
m_usb_tx_string(x) place a string into the TX buffer


MX-Specific: Useful Constants:

  CW 0
CCW 1
A ... K mX-specific ports


MX-Specific: Initialization:

  mx_init( ) set up the m2 to work with the mX board (should always be called first)


MX-Specific: RC Servo Control Outputs

  mx_servo_init(channel) enable an RC servo output channel ((G, H, I, or J)
mx_servo(channel, percent) set an RC servo output channel ((G, H, I, or J) to a percentage between 0.0 and 100.0*


MX-Specific: DC Motor Outputs / Encoder Inputs

  mx_motor(channel, dir, percent) set a DC motor output channel (1 or 2) to a direction (CW or CCW) and a percentage between 0.0 and 100.0
mx_encoder_zero(channel) reset the encoder counter for the specified channel (1 or 2)
result = mx_encoder(channel) read the specified encoder channel (1 or 2)



* You must talk to Jonathan to figure out what this asterisk means



Installation


Windows / AVR Studio

1. Download libsaast-v7.zip and place the libsaast.a and saast.h files beside your main.c file
2. In AVR Studio, go to Project > Configuration Options, switch to the Libraries section, click the "New (Insert)" folder icon near the top right, type ".\" in the text box, and hit enter. Now, select libsaast.a in the lower left pane, and click the Add Library-> button to copy it to the right pane.
3. Switch to the Custom Options section, change to [Linker Options], copy -Wl,-gc-sections into the text box, and click Add (this will optimize linking to leave out things you don't actually need)
4. Add #include "saast.h" to the top of your main.c file


Mac

1. Download libsaast-v7.zip and place the libsaast.a and saast.h files beside your main.c file
2. Edit your Makefile to add libsaast.a to the LIBRARIES line
3. Add #include "saast.h" to the top of your main.c file



The Full Version