MEAM.Design : M2 - Custom Function Library

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`.
	`x = m_write_register(addr, reg, value)`	Write to the slave device (`addr`) to set the value of register `reg` to `value`. Returns 1 if successful, or 0 if there is a communications error.

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

mWII Blob tracker

	`x` = `m_will_open( )`	Initialize the mWII peripheral device. Will return 1 if successful, 0 if it fails.
	`x = m_will_read(buffer)`	Retrieve 12 bytes of data from the mWII into `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 / Atmel 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

Windows / Atmel Studio [Jackie's hack version of installing Libraries]

1. Download libsaast-v7.zip and place the libsaast.a and saast.h files beside your main.c file

2. Unzip your files. Rt-click and "extract all." This will create another folder with the files you need in it.

3. Open the unziped file and Copy the libsaast.a file and paste next to your main.c file

4. Open the unziped file and Copy the saast.h file. Paste in your main.c file (it will be next to your Debug file)

Now you need to add these files to your Library in AmtelStudio

5. Click on the box labeled "Solution Explorer" in the bottom right of the ASF Explorer box on the right side of the development environment (where you type your code)

6. Rt. Click on Libraries and select "Add Libraries"

7. Choose Browse Libraries then click Browse... Find your libsaast.a file and choose it

8. Click OK. it will take a few seconds to load

9. Go back to you Solution explorer. You should see libsaast.a under libraries and saast.h below(but not in) your debug folder

10. Make sure your saast.h file is "included in your path" by rt. Clicking on saast.h and choosing Include In Path

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