Introduction to programming the FRDM/MBED in Java David J.

Transcription

1 Introduction to programming the FRDM/MBED in Java David J. Introduction This document is an introduction to programming a FRDM/MBED in Java for students who have taken the module CO320, Introduction to Object-Oriented Programming, at The University of Kent. It uses a Java API for an MBED-enabled device developed by staff of The Shed. It is particularly intended to support those taking the module CO334, People and Computing. The FRDM/MBED device For the CO334 module, you will be supplied with a piece of hardware called a Freescale FRDM-K64F plus an MBED application shield. For brevity, in this document we will just call the combined unit an MBED. The unit contains a number of input and output devices, such as buttons, a temperature sensor, a speaker and LEDs. It is connected via a USB cable to a computer, from which it can be programmed. For convenience, we will call the computer to which the MBED is connected, the PC, regardless of what it actually is. The USB connection also supplies the MBED with power, so it needs to be connected when being run. Commands can be sent from the PC to the MBED and data values read from it. In this introductory document, we will program the PC to interact with the MBED using Java. You will probably use the BlueJ environment, but that is not a requirement. Any other Java IDE or the command line is appropriate, although those will require a main method see the example Main class below. Getting started In order to interact with the MBED you will need a compiled copy of the Shed API library, which is stored in a file called ShedMBed.jar. You can obtain a copy from: If you are working with BlueJ, then your project folders will need to have a folder created in them called +libs and you must put ShedMBed.jar into +libs. If you are not using BlueJ then you must make ShedMBed.jar available to the compiler and JVM via their classpath. A BlueJ project template, available from: FRDM is pronounced Freedom.

2 contains a complete program that can be used as a basic starting point for coding interactions with the MBED. It already has the required +libs folder and library JAR file. If you are using BlueJ then the Main class can be ignored. The MBed Emulator You will probably want to practice writing programs for the MBED before you have a physical device. A feature of the Shed API library is that if there is no MBED device attached to the PC (or it cannot be connected to for some reason) an emulator will automatically be displayed that looks like this. This can be interacted with via a mouse to mimic pressing the buttons and turning the potentiometers. The LEDs and LCD screen will display outputs. The template program The program contained in the template.zip file provides a pattern for how to connect to an MBED and to write a simple message on its LCD. It will work with both a real device and the emulator. import shed.mbed.lcd; import shed.mbed.mbed; import shed.mbed.mbedutils; public class Program // The object for interacting with the FRDM/MBED. private MBed mbed; /** * Open a connection to the MBED. */ public Program() mbed = MBedUtils.getMBed(); /** * The starting point for the interactions. */ public void run() // Show a message on the LCD. // Where to show the message. int x = 0, y = 0;

3 LCD lcd = mbed.getlcd(); lcd.print(x, y, "Hello, world!"); // Give us time to read the message. sleep(5000); // Clear the display. lcd.clear(); /** * Close the connection to the MBED. */ public void finish() mbed.close(); /** * A simple support method for sleeping the program. millis The number of milliseconds to sleep for. */ private void sleep(int millis) try Thread.sleep(millis); catch (InterruptedException ex) /** * A template main-method class for use from * non-bluej IDEs or the command line. */ public class Main public static void main(string[] args) Program prog = new Program(); prog.run(); prog.finish(); System.exit(0); Compile the project, create a Program object and then call its run method. A "Hello, world!" message should be displayed on the MBED s screen and then cleared after a few seconds. You can call the run method multiple times but you should finally call the finish method to cleanly close the connection to the MBED.

4 For other IDEs or the command line, the Main class contains the main method. For instance, to compile the program from the command line from within the project folder use the command: javac cp.:+libs/shedmbed.jar Main.java to run it use the command: java cp.:+libs/shedmbed.jar Main The MBed and MBedUtils classes The Shed API, shed.mbed, defines classes for interacting with the different input and output devices on the MBED. Interaction is always started by obtaining an object of type MBed via the MBedUtils class. This results in a connection to an attached MBED device by opening a serial port on the PC to allow data to be transferred between the PC and the MBED. If there is no connected device then the emulator will appear. The MBed class defines methods for obtaining objects corresponding to the various devices on the MBED, such as the temperature sensor, the accelerometer, the magnetometer, the two potentiometers, the two buttons on the FRDM board, the joystick on the application shield, the LEDs, the LCD and the Piezo speaker. Each device class defines appropriate methods for interacting with that particular device. Input devices The Thermometer object for the temperature sensor is accessed via the getthermometer method of the MBed object. The Thermometer object has a gettemperature method that returns a double value representing the temperature in Celsius. The API defines the Button class to provide an abstraction for the two FRDM switch buttons and the MBED Joystick. Accessor methods returning Button objects are defined in the MBed class. The FRDM buttons are SW2 and SW3 these names are inscribed on the board (MBed methods getswitch2 and getswitch3). The joystick acts as five mutually-exclusive buttons: called Left, Right, Up, Down and Fire (MBed methods getjoystickleft, getjoystickright, etc.) For instance: Button firebutton = mbed.getjoystickfire(); Button sw2 = mbed.getswitch2(); In general, we will be interesting in knowing whether a button is in the pressed or released state. The central, released position of the joystick is the released state for all five. Pushing the joystick either left, right, up, down or in sets the pressed state for the associated button. The ispressed method of Button returns a boolean value that indicates whether the button is currently pressed (true) or released (false).

5 The Potentiometer class provides an abstraction for the two blue potentiometers. As with Button objects, a Potentiometer object is obtained via an accessor in the MBed; for instance: Potentiometer p1 = mbed.getpotentiometer1(); A Potentiometer object s getvalue method returns a double value in the range 0.0 to 1.0 (inclusive). The Orientation class is used to provide a description for the orientation of the MBED whether it is Up, Down, Left, Right, etc. The MBed object s getmagnetometer method returns a Magnetometer object whose getorientation and getside methods both return Orientation objects. The getmagnetism method of Magnetometer returns an XYZData object that contains an (x,y,z) triplet describing the MBED s magnetic position. However, this data is not considered to be reliable. The getaccelerometerboard and getaccelerometershield methods of the MBed object return instances of an Accelerometer object for the accelerometers located on the FRDM board and the MBED shield respectively. Their getacceleration methods also return an XYZData object describing the MBED s 3D position. Output devices Writing to any of the output devices is performed through the device-specific objects obtained via accessors in the MBed object: getlcd returns an LCD object with methods: print, clear, getwidth, getheight, setpixel, drawcircle, fillcircle, drawline, drawrectangle, fillrectangle and getlocation. getledboard and getledshield both return LED objects with the following methods: getcolor and setcolor. Names for LED colours are defined in the LEDColor class. getpiezo returns a Piezo object that allows some primitive sounds/music to be played. It has the following methods: playnote, playsound and silence.

6 Basic synchronous programming As illustrated in the run method of the Program class in template project, we can write normal looking Java code to interact with the MBED. There, we have a sequence of statements that write some text on the LCD, pause long enough for the text to be read, and then clear the LCD. As an alternative, we might want to obtain some input from the MBED. For instance, read the current value of the temperature sensor and display that: Thermometer temp = mbed.getthermometer(); lcd.print(x, y, "The temperature is " + temp.readtemperature()); The full Java language is available to program the MBED; for instance: // Show a temperature-dependent message on the LCD. if(temp.readtemperature() >= 20) lcd.print(x, y, "Warm"); else lcd.print(x, y, "Cool"); Typically, programs running on the PC continuously monitor the MBED s sensors and respond either with output actions on the MBED or some other form of action on the PC. For instance, one of the potentiometers might be turned to vary a note played on the Piezo speaker: Potentiometer p1 = mbed.getpotentiometer1(); Piezo speaker = mbed.getpiezo(); while(true) double setting = p1.getvalue(); // Play full volume (1.0) at variable frequency. speaker.playsound(1.0, * setting); sleep(100); This example illustrates three themes that occur quite regularly when programming a device such as the MBED: The program is based on an infinite loop because there is no obvious condition for terminating it. The value of a sensor is read inside the loop and used to affect what subsequent actions the program takes.

7 A period of inaction (sleep) is included in the loop to provide a gap between reads of the sensor. The sensor s value is unlikely to change rapidly and there are occasions when a pause will give other parts of the program a chance to act. Continuously reading the value of a sensor like this is often called polling. Busy waiting The polling style of programming based around infinite loops works well for many programs that are only concerned with a single input device, but there are some circumstances where a different approach can be easier to work with. Consider the following code that uses polling to detect the press of button SW2 in order to change the colour of the Shield s LED: Button sw2 = mbed.getswitch2(); LED led = mbed.getledshield(); led.setcolor(ledcolor.blue); // Keep checking to see if the button has been pressed. while(! sw2.ispressed()) sleep(100); led.setcolor(ledcolor.red); In fact, if all we want the program to do is to wait for a particular button to be pressed then it is clearer to use the method, blockuntilpressed, from the Button class: Button sw2 = mbed.getswitch2(); LED led = mbed.getledshield(); led.setcolor(ledcolor.blue); sw2.blockuntilpressed(); led.setcolor(ledcolor.red); One of the problems with loop-based, busy waiting style of coding is that the PC is fully occupied with the process of waiting for something to happen when, most of the time, nothing is happening. Furthermore, if we wanted the program to be doing something else in the loop while waiting for the button press, then we would have to find a way to integrate those other actions with the process of keeping an eye on the state of the button so that the loop could eventually be terminated. In addition, those other actions might also be applicable once the button has been pressed, meaning they would also have to appear after the loop as well. The complex logic is likely to result in the overall code looking very messy. In general, busy waiting for an event to occur is not the best way to interact with devices. Instead, more convenient programming techniques are available using a system of listeners and event-handling code that are activated by interrupts generated by the devices being waited for. These have the added benefit of making it easier to write code in which multiple events are waited for and where the order of occurrence does

8 not have to be governed by the sequential order of the statements in the program. In other words, they support the concept of asynchronous programming. Listeners and Lambdas The following code attaches a listener to the SW2 button, using Java 8 s lambda notation to specify the event-handling code: Button sw2 = mbed.getswitch2(); LED led = mbed.getledshield(); sw2.addlistener( (boolean ispressed) -> if(ispressed) led.setcolor(ledcolor.red); else led.setcolor(ledcolor.blue); ); The -> notation is used to specify the lambda, which is like an anonymous method. On the left-hand side are any parameters and on the right-hand side is the body of the lambda: the code to be executed when an event of interest occurs. The handler is designed to set the Shield s LED to red when SW2 is pressed and blue when it is not pressed. The event handler is called whenever the button is either pressed or released. Shortcuts are often possible in the lambda notation: When the lambda takes only a single parameter, its type and the parentheses are often omitted. When the lambda body is a single, simple statement the curly brackets are often omitted. When the addlistener call is made on the button, the body of the lambda is not executed immediately. Rather, this statement requests that the lambda should be executed whenever the button s state is changed, with the ispressed parameter being set to either true or false depending on whether the button is in the pressed or released state. The MBED will inform the program running on the PC whenever the button s state changes, so the program no longer has to poll the button. So the code following the call to addlistener can be anything else the PC program needs to do while waiting for the button to be pressed. It will be common for listeners to be added to further input devices, such as other buttons or the potentiometers. For instance, we might want to use one of the potentiometers to control the Piezo speaker:

9 Potentiometer p1 = mbed.getpotentiometer1(); Piezo speaker = mbed.getpiezo(); p1.addlistener(value -> speaker.playsound(1.0, value * 1000)); The type of the lambda s parameter is double: a value in the range 0.0 to 1.0. This is used to moderate the frequency of the note played. The remainder of the run method might look as follows: // Set the starting colour. led.setcolor(ledcolor.blue); speaker.playsound(1.0, p1.getvalue() * 1000); while(!finished) sleep(100); In other words, once the listeners have been attached to SW2 and potentiometer 1, as above, the Shield LED s colour is set to its starting colour and the Piezo speaker plays a note based on the initial setting of potentiometer 1. Thereafter, the program loops forever and leaves the listeners to handle the events generated on the monitored input devices. Notice that this style is significantly different from the synchronous style of iteration you are most used to using. Normally, when we write a loop we expect something to happen in the statements inside the loop that causes the loop s condition to become false. Here, it will be an externally-generated event on the MBED that will cause code in one of the listeners to be executed out of the normal sequence of statements in the loop s body. That code will cause a side-effect in the value of the finished variable such that, the next time the loop s condition is evaluated the loop will terminate. The call to sleep in the body of the loop is important in order to avoid the loop s execution dominating the execution of the JVM. The length of the sleep should be short enough that a change to the value of the loop s controlling variable will be detected in good time. The following listener might be used to control the termination of the loop via SW3: Here we assume that some part of the program will eventually set the finished variable to true. For instance, that could be done by a listener attached to another of the buttons.

10 Button sw3 = mbed.getswitch3(); sw3.addlistener(ispressed -> if(ispressed) finished = true; ); In general, attaching listeners is the preferred way to monitor state changes to input devices such as buttons and potentiometers. However, this mode of monitoring is not available for the other input devices, such as the temperature sensor and the accelerometer. Summary This introductory document contains a brief outline of some of the opportunities for writing programs using an MBED via the Shed Java API. The variety of input and output devices available provides the potential for writing some interesting and innovative applications. Several example programs that have been written with the API are available for you to see how the basics are done.