Explore MIT App Inventor - SMS Texting

Google Voice for Texting over Wifi

aaron — Fri, 14 Jun 2013 16:20:49 +0000

Texting Over Wifi: Using Google Voice

Introduction

This tutorial shows how to use the Texting component to send and receive text messages (SMS) over Wifi. This lets
instructors use App Inventor texting examples and exercises with phones that do not have mobile or data plans.

In order to use the Texting component over Wifi, the app user will need a Google Voice account and will also need to download and install the Google Voice app from the Play Store.

Once you get Google Voice set up on your phone, try the AlertMe tutorial.

Under the Hood: How Things Work

Texting over Wifi uses Google Voice to send and receive messages. The mobile Google Voice app is used for receiving messages and the user's Google Voice account is used for sending messages.

Receiving a Message:

Here are some of the internal details for how things work when a message is received.

The phone receives an incoming text message, say, "Hi", from some phone, say, "555-111-2222".
The Android system forwards the message to the Google Voice mobile app, which has been set up to receive messages.
The Google Voice app forwards the message to the Texting component's Broadcast Receiver.
If the Texting component is enabled to receive messages, the Broadcast Receiver forwards the message to the Texting component.
If the Texting component is running (meaning it is visible in the foreground), its MessageReceived (with the arguments 555-111-2222 and Hi for this example) event handler will be invoked.

The MessageReceived method will process the message according to the algorithm specified in its do slot.

Of course most of these details are not visible to the App Inventor programmer, who just needs to worry about the procedure in the Do slot.

Sending a Message:

Here are some of the details for how things work when a message is sent.

Sending a message requires that the Texting component's Message and PhoneNumber properties have been set and that its SendMessage method has been called.
If this is the first message being sent by the app, the user will be prompted to authenticate with their online Google Voice account.

Once authenticated, the SendMessage method will forward the message and phone number to Google Voice.
Google Voice will forward the message to the destination phone number.

Note: if the user sends a message to her own Google Voice number, it will be forwarded back to the phone., which
could be very confusing. This may have implications for how you design your app.

Preliminaries: Logging onto Wifi

A reliable Wifi hotspot is a prerequisite to using the Texting component without a SIM card or mobile account. Use the phone's Settings > Wireless & networks > Wi-Fi to connect to a Wifi hotspot. This may require you to login to the Wifi with a password and may also require you to login to the school's network with a username and password.

Setting Up Your Google Voice Account

The revised Texting component uses Google Voice to send outgoing messages over Wifi. In order to build and test an app that sends text messages over Wifi, the app developer will have to have a Google Voice account. Once the app is developed, users of the app will also have to have Google Voice accounts.

To create a Google Voice account,

Login to your Gmail account.
Click on the More tab on the Google menu bar.
Select the Even More option.
Scroll down to the Google Voice link under Home and Office/.
Follow the instructions there to create a Google Voice number and activate your account.

Installing the Google Voice App

The revised Texting component receives incoming messages over Wifi through the Google Voice mobile app. To download and install Google voice on your phone:

Start the phone's Market or Play Store app.
Search for "Google Voice".
Download and install the app.
Read and approve the app's permission requests.
Start the app and follow the setup instructions.
Set the following Google Voice settings under Voice > Sync and notifications:
Receive text messages > Via the Google Voice app
Text notifications > Off (unless you want your app and Google Voice to notify you)

Authenticating Outgoing Messages

Because outgoing messages are sent through the user's (online) Google Voice account, users of Texting-over-wifi apps will be asked to give the app permission to access the user's account now and in the future. If there are more than one user account on the phone, the user will first be prompted to choose an account.

This description assumes that the user already has an active Google account on the phone. If not, the user will be asked to setup an account or login to an existing Google account.

This authentication process will happen the first time the app sends an outgoing message after it is installed. Depending on how the app and phone are used, the user may never again be asked for permission

In Summary

Congratulations! You have successfully installed Google Voice and are ready to text over Wifi! This will be useful for a variety of Apps that use texting. Now try to build AlertMe, an app that allows you to try this new capability.

Done with Google Voice? Return to the other tutorials here.

Tutorial Version:

App Inventor 1

Tutorial Difficulty:

Advanced

Tutorial Type:

SMS Texting

No Text While Driving (Part 2)

aaron — Fri, 14 Jun 2013 16:20:14 +0000

No Text While Driving, Part 2

Download Refined Version (Book Chapter PDF)

You know that texting while driving is dangerous, so you've created and installed the No Text While Driving app on your phone. Now, when you drive you open that app and let it auto-respond to incoming texts.

But the jingle of the texts coming in is killing you with curiosity-- wouldn't it be great if you could hear the texts spoken aloud? With Part II of the tutorial, you'll extend the app so that it speaks out both the message and who sent it. And since you're making some changes anyway, you'll modify the auto-response so it reports your whereabouts in the reply: "Sorry, I'm driving and I'm at 1600 Pennsylvania Avenue".

Before completing this tutorial you should complete part I.

Getting Started

For this app to work, you'll need to load a text-to-speech module, Text-To-Speech Extended, on your phone. App Inventor and other apps rely on this module for the underlying voice synthesis. If you don't already have it, you can download onto your phone using the Android Market:

On your phone, open the Market app
Search for TTS
Select the app Text-To-Speech Extended to install

Once the Text-To-Speech module is installed, open it to test its features. When it opens, set the default language as desired. Then select "Listen to Preview". If you don't hear anything, make sure the volume on your phone is turned on. You can also change the default Engine which can enhance the quality of the spoken words.

Once the Text-To-Speech module is installed and configured as desired, you can use the TextToSpeech component within App Inventor. Begin by opening App Inventor and your NoTextWhileDriving project from part I. SaveAs the project and name the new copy "NoTextWhileDriving2".

What you'll Learn

The app demonstrates two powerful components:

The LocationSensor component to determine the phone's location, and
The TextToSpeech component to speak the incoming texts aloud.

These components encapsulate some advanced functionality, but using them in building an app is relatively straight-forward.

Set up the Components

Leave the user interface for NoTextWhileDriving, Part II the same as in Part I. But in the Component Designer, add two non-visual components: a LocationSensor and a TextToSpeech component. You do not need to set any properties of the components.

Add behaviors to the components

The behavior for part I of No Text While Driving was: "when a text is received, the message the user has put in MessageTextbox is sent as a text message response to the sender."

For part II, the behavior will be changed to: "when a text is received, it is spoken aloud and a message, including the text in MessageTextbox and the phone's current location, is sent in response to the sender."

Speaking the text aloud

When a text message is received by the phone, the Texting.MessageReceived event is triggered. The blocks from Part I handle this event by setting the PhoneNumber and Message properties of the Texting component appropriately and then sending the response text.

Extend the blocks from Part I by using the TextToSpeech component to speak both the sender's phone number and the message. You'll add the following blocks to the existing Texting.MessageReceived blocks:

Block type	Drawer	Purpose
TextToSpeech1.Speak	TextToSpeech1	Speak out the message received
make text	Text	Build the words that are to be spoken
text ("message from")	Text	First words spoken, put a space at end
number	My Definitions	This is the number the original text was received from
text ("")	Text	Put a space in between number and message
messageText	My Definitions	This is the original message received

The blocks should look like this:

How the blocks work

After the response is sent, the TextToSpeech1.Speak function is called. You can plug any text object into the message slot of the Speak function. In this case, make text is used to build the words to be spoken, including the text "message from", the phone number from which the message was received (number), a blank text, and the message received (messageText). If the text "hello" was received from the number "111-2222", the words "message from 111-2222. hello." would be spoken.

Test the behavior. You'll need a second phone to test the behaviors in this app. From the second phone, send a text to the phone that is running the app. Does the second phone speak the text aloud? Does it still send an automated response?

Adding location information to the auto-response

Next, add a LocationSensor.LocationChanged event handler which places the current address into a variable, lastKnownLocation. When a text comes in, the value of that variable can be added to the response message. Here are the blocks you'll need:

Block type	Drawer	Purpose
def variable (lastKnownLocation)	Definitions	Create a variable to hold the last read address
text ("unknown")	Text	Set the default value in case the phone's sensor is not working
LocationSensor1.LocationChanged	LocationSensor1	This is triggered on the first location reading and every change
set lastKnownLocation to	My Definitions	Set this variable to be used later
LocationSensor1.CurrentAddress	LocationSensor1	This is a street address such as "2222 Willard Street, Atlanta, Georgia"

Here are the blocks:

How the Blocks Work

LocationSensor1.LocationChanged is called the first time the sensor gets a reading and each time the phone is moved enough to trigger a new reading. These blocks just place the current (street) address into the variable lastKnownLocation, which you'll use later when you change the auto-response that is sent out.

Modify the message with location information

Next, modify the Texting1.MessageReceived event-handler so that the current address is added to the response. You'll need the following blocks:

Block type	Drawer	Purpose
make text	Text	If there is a location reading, build a compound text object
MessageTextBox.Text	MessageTextBox	This is the (custom) message in the text box
text ( "My location is: ")	Text	This will be spoken after the custom message (note the leading space)
global lastKnownLocation	LocatonSensor	This is an address such as "2222 Willard Street, Atlanta, Georgia"

The blocks should look like this:

How the Blocks Work

Instead of directly sending a message of the text in MessageTextbox.Text, the app first builds a message using make text. It combines the response text in MessageTextBox.Text with the text " My location is " and then the variable lastKnownLocation.

Test the behavior. From the second phone, send a text to the phone that is running the app. Does the second phone receive the response text? Does it include location information?

Final Program

Variations

Once you get the app working, you might want to explore some variations. For example,

Write a version that lets the user define custom responses for particular phone numbers.
Write a version that sounds an alarm when a text is received from a number in a "notify" list.

Review

Here are some of the ideas covered in this tutorial:

The TextToSpeech component takes any text object and speaks it aloud. It relies on an Android module, Text-To-Speech Extended, which must be downloaded to the phone for the app to work.
make text is used to piece together (concatenate) separate text items into a single text object.
The LocationSensor component can report the phone's latitude, longitude, and current street address. To ensure that it has a reading, you should access its data in its LocationChanged event-handler, which is triggered the first time a reading is made and on every change thereafter.

Scan the Sample App to your Phone

Scan the following barcode onto your phone to install and run the sample app.

Or download the apk

Download Source Code

If you'd like to customize this sample in App Inventor, download the source code to your computer, then open App Inventor, go to the My Projects page, and choose More Actions | Upload Source.

MIT and Google are grateful to Professor David Wolber, CS Professor at The University of San Francisco, for developing this tutorial.

Done with No Text While Driving, Part 2? Return to the other tutorials here.

Tutorial Version:

App Inventor 1

Tutorial Difficulty:

Advanced

Tutorial Type:

SMS Texting

No Text While Driving

aaron — Fri, 14 Jun 2013 16:19:45 +0000

No Text While Driving

Download Refined Version (Book Chapter PDF)

This tutorial demonstrates how an app can respond to text messages automatically. You'll build an app that sends back a response when a text message is received. The idea for the app came from University of San Franciso student Daniel Finnegan.

This tutorial assumes you are familiar with the basics of App Inventor-- using the Component Designer to build a user interface, and using the Blocks Editor to specify event-handlers.If you are not familiar with the basics, try stepping through some of the basic tutorials before continuing.

Getting Started

Connect to the App Inventor web site and start a new project. Name it NoTextWhileDriving, and also set the screen's Title to "NoTextWhileDriving". Open the Blocks Editor and connect to the phone.

Introduction

You'll design the app so that it sends a response to any text message received. You'll also allow the user to customize the response sent.

The tutorial introduces the following App Inventor concepts:

The Texting component for sending texts and processing received texts.
The TinyDB database component for saving the customized message even after the app is closed.

Set up the Components

The user interface for NoTextWhileDriving is simple: it has a text box for the response message and a button for submitting a change to this message. It also has two checkboxes: one to decide whether or not you want to be receiving messages and one to choose to enable Google Voice. This is useful for texting if your phone doesn't have a SIM card. Visit the Texting over Google Voice tutorial to learn more about this.

You'll also need a Texting component and a TinyDB component, both of which will appear in the "non-visual" component area. A table of detailed instructions for designing the components is below, but you can also build it from the following picture of what it should look like:

The components listed below were used to create the designer window shown above. Drag each component from the Palette into the Viewer and name it as specified below:

Component Type	Palette Group	What you'll name it	Purpose of Component	Component Settings
Label	Basic	PromptLabel	Let the user know how the app works	Set the Text to "The text below will be sent in response to all texts while this app is running."
Label	Basic	ResponseLabel	Displays what text will be sent to incoming messages.
TextBox	Basic	NewResponseTextbox	User will enter custom response here	Set the Hint to "Enter custom response."
Button	Basic	SubmitResponseButton	User clicks this to submit new response	Set the text to "Submit Response."
CheckBox	Basic	CheckBoxReceivingEnabled	Let the user choose if they want to receive messages.
CheckBox	Basic	CheckBoxGvEnabled	Let the user choose if they want to respond using Google Voice.
Texting	Social	Texting1	The component that processes the texts
TinyDB	Basic	TinyDB1	The component that will store the response in the database

Add behaviors to the components

NoTextWhileDriving has the following behaviors:

When a text is received, the message displayed in ResponseLabel is sent as a text message response to the sender.
When the user modifies the custom message in NewResponseTextbox and clicks the SubmitResponseButton , the new message is saved persisently in the phone's database.
When the app begins, the custom message is loaded from the database into ResponseLabel.

1. Responding to a text

When a text message is received by the phone, the Texting.MessageReceived event is triggered. Your app should handle this event by setting the PhoneNumber and Message properties of the Texting component appropriately and sending the response text.

You'll need the following blocks:

Block type	Drawer	Purpose
Texting1.MessageReceived	Texting1	Event-handler triggered when the phone receives a text
set Texting1.PhoneNumber to	Texting1	Set the PhoneNumber property before sending
value number	My Definitions	This is the phone number of the person who sent the text
set Texting1.Message to	Texting1	Set the Message property before sending
ResponseLabel.Text	ResponseLabel	This is the message the user has entered
Texting1.SendMessage	Texting1	Send the message

The blocks should look like this:

How the Blocks Work

When the phone receives any text message, the Texting1.MessageReceived event is triggered. The phone number of the sender is in the argument number, and the sender's message is in the argument messageText.

In response, the app sends a text message to the sender. To send a text, the app sets the two key properties of the Texting component: PhoneNumber and Message. Texting.PhoneNumber is set to the number of the sender, and Texting.Message is set to the text in ResponseLabel -- this might be the default, "I'm driving right now, I'll contact you shortly.", or the user may have modified it. Once these properties are set, Texting1.SendMessage is called to actually send the response text message.

The if block prevents the app from sending the automatic reply if it receives its own message. This would happen, for example, if the user is texting their own number to test the app.

Test the behavior. You'll need a second phone to test this behavior. From the second phone, send a text to the phone that is running the app. You can set up one phone with Google Voice or start two emulators to communicate with one another to test this behavior. Does the second phone receive the response text? If that works, try modifying the response message and sending another message from the second phone. Is the new response sent?

2. Storing the custom response

The app so far works, but if you close the app and reopen it, the custom message will be lost. To make things more convenient for the user, store the custom response message they enter into a database using the TinyDB component.

TinyDB provides two blocks: StoreValue and GetValue . The former allows you to store a tagged piece of information, while the latter let's you retrieve one.

You'll need the following blocks to store the custom message:

Block type	Drawer	Purpose
SubmitResponseButton.Click	SubmitResponseButton	User clicks this button to submit new response message
ResponseLabel.Text	ResponseLabel	Sets the response to be what the user inputs.
NewResponseTextbox.Text	NewResponseTextbox	The response message entered by the user is here
TinyDB1.StoreValue	TinyDB1	Store the custom message in the phone's database
text ("responseMessage")	Text	Use this as the tag for the data
ResponseLabel.Text	ResponseLabel	The response message entered by the user is displayed here after the user submits their new response.

The blocks should look like this:

How the Blocks Work

When the user clicks the SubmitResponseButton, the app will store the response message entered by the user as the shown text that will be sent. The text in this label (ResponseLabel.Text) will be stored in TinyDB. The text responseMessage is used as a tag to uniquely identify the information-- later, you'll use that same tag to retrieve the message from the database.

3. Retrieving the saved response message

Program the Screen1.Initialize event-handler so that the saved custom response message is retrieved from the database and placed in ResponseLabel. Check the retrieved data to make sure there's something there-- after all, the first time the app is used, the database will not have any message saved. If there is a stored message, place it in the ResponseLabel so that the user can see it and so that it will be used to respond to incoming texts.

You'll need the following blocks:

Block type	Drawer	Purpose
def variable ("response")	Definitions	A temporary variable to hold the retrieved data
text (blank)	Text	Initial value for the variable can be anything
Screen1.Initialize	Screen1	This is triggered when app begins
Texting1.ReceivingEnabled	Texting1	Sets the app so that it receives SMS text messages
number (3)	Number	The app is initialized to receive text messages while the app is running or when it's not
CheckBoxGvEnabled.Checked	CheckBoxGvEnabled	Sets status of the Google Voice Enabled checkbox
Texting1.GoogleVoiceEnabled	Texting1	If Google Voice is enabled, SMS messages will be sent over Google Voice
if else test	Control	To ask if texting should be enabled.
not= block	Math	Check if the retrieved value is not equal to (=) 1
Texting1.ReceivingEnabled	Texting1	Lets the user decide whether or not the app will received SMS messages
CheckBoxReceivingEnabled.Checked(x2)	CheckBoxReceivingEnabled	Sets status of the Receiving Enabled checkbox.
true	Logic	Sets the app to receive text messages
false	Logic	Sets the app to not receive text messages
set Response	Definitions	Sets the variable to the value retrieved from db.
TinyDB1.GetValue	TinyDB1	Get the stored response text from the database
text ("responseMessage")	Text	Plug into tag slot of GetValue, make sure text is same as was used in StoreValue above
if test	Control	To ask if the retrieved value has some text
> block	Math	Check if length of retrieved value is greater than (>) 0
length test	Text	Check if length of retrieved value is greater than 0
global response (x2)	My Definitions	This variable holds the value retrieved from GetValue
number (0)	Math	To compare with length of response
set ResponseLabel.Text to	Message	If we retrieved something, place it in ResponseLabel

The blocks should look like this:

How the Blocks Work

When the app begins, the Screen1.Initialize event is triggered. The app calls the TinyDB1.GetValue with a tag of responseMessage-- the same tag used when you stored the user's entry earlier. The resulting value is placed in the variable response. When the app starts, we set the Texting component to have receiving enabled, but not Google Voice, which is displayed on the user interface. ReceivingEnabled takes a number value 1 (receiving disabled), 2 (receiving enabled while app is running), or 3 (receiving enabled when app is running and is not running)

The variable response is used so that the value returned from the database can be checked. If it has a length of 0, then there was no database entry with a tag of responseMessage-- something that will occur the first time a user runs this app. But if the length is greater than 0, the app knows that a custom response has been stored previously, and the retrieved value can be placed in the ResponseLabel which the user will see and which is used as the message for any response texts sent.

Test the app. Enter a new response message in the NewResponseTextbox and click the SubmitResponseButton. Then restart the app by clicking the Restart App button in the Blocks Editor. This will cause the app to re-initialize just like it will when a user closes the app and reopens it later. Does the custom message you entered appear?

Selecting Response Settings

The user interface has two checkboxes that the user can toggle: whether Receiving is enabled and whether Google Voice is enabled. The first allows the user to decide whether or not they want to be receiving messages. The second lets the user decide if they want to send messages from their own phone number or from a Google Voice account. When the user toggles these switches, the changes are communicated to the Texting component which enables or disables these properties as marked.

You'll need the following blocks.

Block type	Drawer	Purpose
CheckBoxGvEnabled.Changed	CheckBoxGvEnabled	Detects if the user toggles this control.
Texting1.GoogleVoiceEnabled	Texting1	Sets whether or not Google Voice is enabled
CheckBoxGvEnabled.Checked	CheckBoxGvEnabled	Returns true or false value.
CheckBoxReceivingEnabled.Changed	CheckBoxReceivingEnabled	Detects if the user toggles this control.
if else block	Control	Checks whether or not receiving is enabled.
= block	Math	Checks whether or not receiving is enabled.
true	Logic	Checks whether or not receiving is enabled.
CheckBoxReceivingEnabled.Checked	CheckBoxReceivingEnabled	Returns true or false value.
Texting1.ReceivingEnabled(x2)	Texting1	Sets whether or not receiving is enabled.
number(1)	Math	Sets ReceivingEnabled as false.
number(3)	Math	Sets ReceivingEnabled as true.

The blocks should look like this:

Test the app. Try texting your Android device when the "Receiving Enabled" is checked and then when it is not checked. Do you receive texts when it is unchecked? Try texting over Google Voice. If any of these features aren't working like you expect them to, go back and look at the blocks again!

No Text While Driving, Final Program

Variations

Once you get the No Text While Driving app working, you might want to explore some variations. For example,

Write a version that speaks the received texts aloud. You'll need to use the TextToSpeech component.
Write a version that lets the user define custom responses for particular phone numbers.
Write a version that sends custom responses based on the user's location (e.g., I'm in church...)

Review

Here are some of the ideas covered in this tutorial:

The Texting component can be used both to send text messages and process the ones that are received.
The TinyDB component is used to store information persistently, in the phone's database, so that it there each time the app is opened.

Scan the Sample App to your Phone

Scan the following barcode onto your phone to install and run the sample app.

Or download the apk

Download Source Code

If you'd like to work with this sample in App Inventor, download the source code to your computer, then open App Inventor, go to the My Projects page, and choose More Actions | Upload Source.

MIT and Google are grateful to Professor David Wolber, CS Professor at The University of San Francisco, for developing this tutorial.

Done with No Text While Driving? Return to the other tutorials here.

Tutorial Version:

App Inventor 1

Tutorial Difficulty:

Advanced

Tutorial Type:

AlertMe

aaron — Fri, 14 Jun 2013 16:13:33 +0000

AlertMe: Texting in the background, when app is not running

The AlertMe app receives alert messages, and notifies the user even when the app is not currently running. If the app is running (visible on the screen), when it receives an SMS, the message will be displayed on the screen. If it's not running, the user will receive a Notification in the status bar, which can be viewed by pulling down the status bar. Tapping on the notification will start the app and display the message. The user can then click the Acknowledge button to send an acknowledgment to the sender that the alert has been received.

If you are using a device that does not have regular SMS enabled through a cell phone carrier and want to do texting over the internet (IP/wifi), make sure you have a Google Voice account and you have the Google Voice app set up on your phone or tablet. For more information on how to do this, see the Google Voice for Wifi Texting tutorial. When you set up the texting component in the designer, be sure you have checked the GoogleVoiceEnabled property.

The Designer

The interface of the app is pretty simple. It displays the time, phone number, and message of each of the alerts, as well as an acknowledge button. What really drives this app is the Texting component that you will add. The components are:

Component Type	Palette Group	What you'll name it	Purpose of Component
Label	Basic	LabelHeader	Displays the "Alerts" header.
Label	Basic	LabelAlerts	Displays the incoming messages in a log Set width and height to Fill Parent
Button	Basic	ButtonAck	Sends an achknowledgment to the alert sender.
Clock	Basic	Clock1	Used to generate a time stamp in the message log.
Texting	Social	Texting1	Receives and sends messages over Wifi. Only if you are using texting over wifi through Google Voice: *Check the GoogleVoiceEnabled* property.**

When you're done, the designer should look like this.

The Blocks Editor

The blocks have to handle two events: receiving a message and sending an acknowledgment. In each of these cases, they have to know who sent the message and what it said. We'll approach each of these actions in turn.

Variables

Since both procedures require that we know the alert message and who sent it, we will define two globalvariables: alertPhoneNumber and alertMessage.

The Message Received Block

Incoming messages are handled by the MessageReceived block, which takes two arguments, the number and the messageText. For this app, we store the values of these arguments in our global variables, alertPhoneNumber and alertMessage respectively, and then construct a log entry and display it on the label using LabelAlerts.Text.

Sending an Acknowledgment

The user can acknowledge an alert by sending a message back to the sender. This is done using ButtonAck.Click, which constructs the message and sends it as shown here.

Variations

Now that you have AlertMe working, here are some variations on the program you can make.

Modify the function of the Acknowledge button so you can choose to send different text, such as choosing between "What's up?", "On my way", and "Call you later."
Change the blocks so the user gets an automatically generated response (without you clicking a button). This could be a setting you could enable if you are away from your phone or in a meeting.

Scan the Sample App to your Phone

Scan the following barcode onto your phone to install and run the sample app.

Or download the apk

Download Source Code

If you'd like to work with this sample in App Inventor, download the source code to your computer, then open App Inventor, go to the My Projects page, and choose More Actions | Upload Source.

Done with AlertMe? Return to the other tutorials here.

Tutorial Version:

App Inventor 1

Tutorial Difficulty:

Advanced

Tutorial Type:

Broadcast Hub

aaron — Fri, 14 Jun 2013 16:13:05 +0000

BroadcastHub

Download Refined Version (Book Chapter PDF)

In this tutorial, you'll write an app that automatically responds to texts messages and broadcasts texts messages it receives to a list of phone numbers.The app is inspired by FrontLineSMS, a tool that has been used in developing countries to monitor elections, broadcast weather changes, and in general connect people that don't have access to the web but do have phones and mobile connectivity.

FrontLineSMS is software that runs on a computer with a phone plugged into it. The computer and plugged-in phone serve as a hub for SMS text communication amongst a group. You'll write a version of the software that runs on an Android phone, thus allowing the hub to be as mobile as the phones it connects.

This tutorial assumes you are familiar with the basics of App Inventor-- using the Component Designer to build a user interface, and using the Blocks Editor to specify event-handlers. If you are not familiar with the basics, try stepping through some of the basic tutorials before continuing.

The tutorial also assumes you have completed the TextGroup tutorial and thus are familiar with the basics of the Texting component.

Getting Started

Connect to the App Inventor web site and start a new project. Name it BroadcastHub, and also set the screen's Title to "BroadcastHub". Open the Blocks Editor and connect to the phone.

Introduction

BroadcastHub processes text messages that are received in the following manner:

If the text message is from an unknown source, the app responds with a text that invites that source to join the broadcast list.
If the text message “joinabc” is received, the app adds the sender to the broadcast list.
If the text message is from a number already in the broadcast list, the message is broadcast to all numbers in the list.

The tutorial covers the following App Inventor concepts:

The Texting component for sending texts and processing received texts.
List variables to keep track of the numbers to text.
The Clock.Timer block that is used to cause an app to repeat operations on a list of data (the list of phone numbers) each time the Timer goes off

Setting up the Components

BroadcasterHub facilitates communication between mobile phones. Those phones need not have the BroadcasterHub app installed, or even be smart phones. The app is the hub, and the app's user interface is only for the administrator of the communications network.

For this sample, that user interface is simple: it will display the current broadcast list -- the list of phone numbers which have registered for the service-- and it will report all texts it receives and broadcasts.

To build the interface, add the following components:

Component Type	Palette Group	What you'll name it	Purpose of Component
Label	Basic	BroadcastListLabel	This will display the phone numbers that are registered.
Label	Basic	LogLabel	This will display a log of the texts received and broadcast.
Texting	Social	Texting1	The component that processes the texts
TinyDB	Basic	TinyDB1	To store the list of registered phone numbers

Set the Width of each of the labels to "Fill Parent" so that they span the phone horizontally. Set the Height for the labels to 200 pixels.
Set the Text property of BroadcastListLabel to "Broadcast List...".
Set the Text property of LogLabel to blank.

BroadcastHub should look like this after its front-end is designed:

Add behaviors to the components

The activity for Broadcast Hub is not triggered by the user entering information or clicking a button, but by texts being received from outside sources. You'll need the following behaviors:

When the text message is from an unknown source, the app responds with a text that invites that source to join the broadcast list.
When the text message "joinabc" is received, register the sender as part of the broadcast list.
When the text message is from a number already in the broadcast list, the message is broadcast to all numbers in the list.

Start by creating the first behavior-- when you receive a text, send a message back to the sender inviting them to text a code, "joinabc", in order to register for the group. You'll need the following blocks:

Block type	Drawer	Purpose
Texting1.MessageReceived	Texting1	Event-handler triggered when the phone receives a text
set Texting1.PhoneNumber to	Texting1	To set the number for the return text
value number	My Definitions	Argument of MessageReceived, it is the phone number of sender
set Texting1.Message	Texting1	To set the invite message to send
text	Text	The invite message
Texting1.SendMessage	Texting1	Send it!

The blocks should look like this:

How the Blocks Work

Texting1.MessageReceived is triggered when any text message is received on the phone. The blocks within the event-handler set the PhoneNumber and Message of the Texting1 component, then send the message.

Test the behavior. You'll need another phone besides the one on which the app resides. From the second phone, send a text "hello" to the phone running the app. The second phone should receive a text that invites them to the group.

Handling the "joinabc" text message

Create the blocks for the second behavior: "when the text message "joinabc" is received, add the sender to the broadcast list." First, you'll need to define a list variable, BroadcastList, to store the phone numbers that register. From Definitions, drag out a def var block and name it "BroadcastList". Initialize it with a make a list block from Lists:

Next, modify the Texting1.MessageReceived event-handler so that it adds the sender's phone number to the BroadcastList if the message received is "joinabc". After you add the number to the list, display the new list in the BroadcastListLabel. You'll need the following blocks:

Block type	Drawer	Purpose
ifelse	Control	Depending on message received, you'll do different things
= block	Math	The test will be: is messageText equal to "joinabc"
value messageText	My Definitions	Plug into = block
text ("joinabc")	Text	Plug into = block
add items to list	Lists	To add the sender's number to BroadcastList
BroadcastList	My Definitions	The list
value number	My Definitions	Plug in as item of add items to list
set BroadcastListLabel.Text to	BroadcastListLabel	Display the new list
BroadcastList	My Definitions	Plug in to set BroadcastListLabel.Text to block
set Texting1.Message to	Texting1	Prepare Texting1 to send message back to sender
text ("congrats, you ...")	Text	Congratulate sender for joining group

The blocks should look like this:

How the Blocks Work

The first row of blocks sets Texting1.PhoneNumber to the phone number of the message that was just received. The app then asks if the messageText was of the special code "joinabc". If so, the sender's phone number is added to the BroadcastList, and a congratulations message is sent. If the messageText is something other than "joinabc", the reply message is just the invitation message from before. After the ifelse block, the reply message is sent (bottom row).

Test this behavior. From a second phone, send the text message "joinabc" to the phone on which the app is running. Do you recieve the correct reply? Try sending a different text message as well to check if the ifelse is working correctly.

Broadcasting Messages

Next, you'll add the behavior so that the app broadcasts messages to the numbers in BroadcastList, if the message arrives from a number in BroadcastList. You'll need an additional ifelse block to check if the number is in the list, and a Clock.Timer block to broadcast the message to each item in the list. Here are all the blocks you'll need:

Block type	Drawer	Purpose
ifelse	Control	Depending on whether sender is already in list, you'll do different things
is in list?	Lists	Checks to see if something is in a list
global BroadcastList	My Definitions	Plug into list slot of is in list?
value number	My Definitions	Plug into list slot of is in list?
Clock.Timer	My Blocks	To repeatedly send out message to all in list
global BroadcastList x2	My Definitions	Plug into list slot of select list item
set Texting1.Message to	Texting1	To set the message
value messageText	My Definitions	The message that was received and to be broadcast
set Texting1.Message to	Texting1	To set the phone number
set Clock.TimerEnabled x2	Clock1	To turn the timer on/off
set nTicks x2	My Definitions	Sets the value of nTicks
select list item	Control	To grab an item from the list

The blocks should look like this:

How the Blocks Work

We've just set up a timer to send a text message to each number in the list, BroadcastList.

A timer performs some action each time the clock ticks. To control the timer, define a global variable named nTicks. We will set this variable initially to the number of phone numbers in the list.  And then we will subtract 1 from the variable each time we send a message. 

A timer is done in two parts.  In TextingMessage1.Received we will no longer send the message. Instead, we will initialize the global nTicks variable to the length of the BroadcastList list.  And we will enable the Clock1.

The second part is done using a Clock1.Timer block. This block will contain the Texting1.SendMessage command. Each time the clock ticks the following steps will be performed:

Select a number from the phoneNumbers list using the nTicks as the index.
Set the Texting1.PhoneNumber to the selected number.
Send the text message using Texting1.SendMessage.
Subtract 1 from the nTicks variable.
If the nTicks is less than or equal to 0, disable the clock

The behavior is complex enough that it requires a "nested" ifelse block. If the phone number of the received message is already in the list, the foreach block is executed and the message relayed to all in the list. If the number is not in the list, the outer else-do clause is executed, and it asks another question, which is the test of the nested ifelse block: is the messageText equal to "joinabc". The app then branches one of two ways based on the answer.

In general, if and ifelse blocks can be nested to arbitrary levels, giving you the power to program arbitrarily complex behaviors.

Test this behavior. First, have two different phones register with the app by texting "joinabc" to the phone which is running the app.Then text another message from one of the phones. Both phones should receive the text.

Logging the broadcasted texts

When a text is received and broadcast out to the other phones, the app should log that occurrence to the app so the administrator can monitor the activity. Earlier, you added the label LogLabel to the user interface for this purpose. Now, you'll code some blocks that change LogLabel each time a new text arrives.

You need to build a text that says something like "message from 111-2222 broadcast". The 111-2222 is not fixed data, but is the value of the variable number that comes with the MessageReceived event. So to build the text, you'll concatenate the first part "message from" with the variable number and finally with the last part of the message, the text "broadcast".

There are two functions in the Text drawer to build text. One is the join function, which joins two pieces of text. Another function, make text, is also available and more convenient to use than join when you have more than two parts. You'll use it for this behavior. Here are all the blocks you'll need:

Block type	Drawer	Purpose
set LogLabel.Text to	LogLabel	Display the log here
make text	Text	Build a text object out of multiple parts
text ("message from")	Text	Report message
value number	My Definitions	The number of the sender
text ("broadcast\n")	Text	Text is "message from 111-2222 broadcast" with newline
LogLabel.Text	LogLabel	Add new log to the previous ones

The blocks should look like this:

How the Blocks Work

After broadcasting the message to all the numbers in BroadcastList , the app now modifies the LogLabel to include a report of the just broadcasted text. If the sender's number (value number) is "1112222", then the make text will build the text object:

message from: 1112222 broadcast

along with the log reports that were already in LogLabel.Text from previously received texts. The "\n" is the newline character that causes the old reports to be displayed on the next line, e.g.,

message from: 1112222 broadcast
message from: 555-6666 broadcast

Storing the BroadcastList in a Database

As is, the app works, but every time you close the app the BroadcastList will be lost and everyone would have to re-register. To fix this, you'll use the TinyDB component to store and retrieve the BroadcastList to and from a database. TinyDB allows you to store data persistently-- even if the app is closed, the next time you open the app the data will be there.

The general scheme for storing data persistently is the following: When the app begins, load the list from the database into a variable (e.g., BroadcastList ). Then, each time a new item is added to the list, update the database version of the list.

Start by coding the blocks to store the list in the database. With the TinyDB component, a tag is used to identify the data and distinguish it from other data stored in the database. In this case, you can tag the data as "broadcastList". Do the following:

Drag out a TinyDB1.StoreValue block from the TinyDB1 drawer.
Create a text block and give it the text "broadcastList". Place this text block as the tag of StoreValue.
Drag out a reference to BroadcastList from My Definitions . Place it as the value argument of StoreValue.
Place the StoreValue block right below the blocks that add an item to the BroadcastList.

The bottom part of the modified Texting1.MessageReceived event-handler should look like the following:

How the Blocks Work

TinyDB1.StoreValue stores the data in BroadcastList to a database with a tag that you can later use to retrieve the data into your app. In this case, the tag is the text, "broadcastList", and he value is the actual list BroadcastList.

Loading the BroadcastList from a Database

Now add the blocks for loading the list back in each time the app begins. When the app begins, the Screen1.Initialize event is triggered, so your blocks will go in that event-handler. You’ll call TinyDB.GetValue, using the same tag you used to store the list (“broadcastList”). Check if the returned value is a list, because it won’t be if there isn’t any data in the list yet.

The blocks should look like:

How the Blocks Work

The blocks first define a variable, valueFromDB, which is used to temporarily store the data returned from the database. When the app begins, the Screen1.Initialize event is triggered. TinyDB.GetValue is called, and the data from the database is placed in valueFromDB.

The variable is then checked to see if it is a list. If it is not, that means there was no data for the tag “broadcastList” in the database, and an empty text has been returned. This will happen the first time a user opens the app.

If valueFromDB is a list, the list is placed into the variable BroadcastList and the list is displayed.

Test this behavior. Choose Restart App which will trigger the Screen1.Initialize. Do the numbers registered earlier appear?

Display BroadcastList with each number on separate lines

Create a procedure displayBroadcastList, which displays the list with each phone number on a separate line. Be sure and call the procedure from below the add items to list block so that the updated list is displayed.

For help displaying the list on separate lines, see Displaying a List.

You'll need the following blocks:

Block type	Drawer	Purpose
procedure ("displayBroadcastList")	Definitions	Create the procedure
set BroadcastListLabel.Text to	BroadcastListLabel	Display the list here
text ("Phone Numbers...")	Text	The header for the list
foreach	Control	Iterate through the numbers
name pnumber	in the foreach	Name the foreach variable "pnumber". This is the current item of the foreach
BroadcastList	My Definitions	Plug into in list slot of foreach
set BroadcastListLabel.Text to	BroadcastListLabel	Modify with each of the numbers
make text	Text	Build a text object from multiple parts
BroadcastListLabel.Text	BroadcastListLabel	Add to the label on each iteration of foreach
text ("\n")	Text	Newline character so that next number is on next line
value pnumber	My Definitions	The current number from the list

The displayBroadcastList procedure should look like this:

How the Blocks Work

The foreach in displayBroadcastList successively adds a phone number to the end of the label, placing a newline character in between each item.

Of course this procedure will not do anything unless you call it: you should add two calls to the procedure: one within the Texting1.MessageReceived event-handler, and one within the Screen1.Initialize event-handler. The call displayBroadcastList block can be found in My Definitions, and it should replace the blocks that directly set the BroadcastListLabel.Text to the list. You can see how these calls to displayBroadcastList should look in the snapshot of the final version below.

Test this behavior. Try adding some more phone numbers to the list. Do the registered phone numbers now appear on separate lines?

Broadcast Hub, Final Version

Variations

Once you get the Broadcast Hub app working, you might want to explore some variations. For example,

Allow client phones to remove themselves from the list by texting "quitabc" to the app.
Let the hub administrator (the user of your app) add and remove numbers from the broadcast list.
Let the hub administrator specify numbers that should not be allowed into the list.

Review

Here are some of the ideas covered in this tutorial:

Apps can react to events, like a text being received, that are not initiated by the user of the app.
Nested ifelse and foreach blocks can be used to code complex behaviors.
The make text block can be used to build a text object out of multiple parts.
TinyDB can be used to store and retrieve data from a database. A general scheme is to call StoreValue to update the database whenever the data changes, and call GetValue to retrieve the database data when the app begins.

Scan the Sample App to your Phone

Scan the following barcode onto your phone to install and run the sample app.

Or download the apk

Download Source Code

If you'd like to work with this sample in App Inventor, download the source code to your computer, then open App Inventor, go to the My Projects page, and choose More Actions | Upload Source.

MIT and Google are grateful to Professor David Wolber, CS Professor at The University of San Francisco, for developing this tutorial.

Done with BroadcastHub? Return to the other tutorials here.

Tutorial Version:

App Inventor 1

Tutorial Difficulty:

Advanced

Tutorial Type:

TextGroup (Part 2)

aaron — Fri, 14 Jun 2013 16:12:40 +0000

Text Group Part II: Adding and Removing Members

What you're building

This tutorial extends the Text Group tutorial. That app sent a text to a fixed list of phone numbers, and only the programmer could change the numbers in the list. The app in this tutorial allows the user to add and remove the phone numbers in the list, and it stores the list persistently in a database.

Getting started

Connect to the App Inventor web site and open your TextGroup project (if you haven't completed that tutorial, do so now before continuing). SaveAs the app and name it "TextGroup2". You can leave the screen's Title as "Text Group". Open the Blocks Editor and connect to the phone.

Introduction

You'll design the app so that the user adds phone numbers to the group by choosing from the phone's contact list, and removes them by choosing from the items already in the group.. You'll store the list of numbers in a database so that they are there even when the app is closed and re-launched.

The tutorial covers the following App Inventor components and concepts:

The foreach block for repeating operations on a list.
The PhoneNumberPicker component for accessing the phone's contacts.
The ListPicker component for allowing the user to choose a number for removal.
The Texting component for sending texts.
The TinyDB database component for storing the phone list in a database.

Set up the Components

The user interface for Text Group, Part II has a textbox, button, and status label for sending the group text, just as in Part I. If you performed a SaveAs to begin this project, those components should already be in the view. You should then add a PhoneNumberPicker and ListPicker components for adding and removing phone numbers from the list, along with a Texting component and a TinyDB component, both of which will appear in the "non-visual" component area. A table of detailed instructions for designing the components is below, but you can also build it from the following picture of what it should look like:

The components listed below were used to create the designer window shown above. The first five were part of TextGroup so will already be there if you built that app and performed a SaveAs to begin this one. You'll need to drag each of the other components from the Palette into the Viewer and name it as specified below:

Component Type	Palette Group	What you'll name it	Purpose of Component
TextBox	Basic	MessageText	User will enter message here.
Button	Basic	TextGroupButton	User enters the message here
Label	Basic	StatusLabel	Reports when texts have been sent
Texting	Social	Texting1	The component that sends the texts
Clock	Basic	Clock1	The component that designates when to send the texts
Label	Basic	GroupHeadingLabel	Header for the list of phone numbers that will appear
Label	Basic	MembersLabel	This is where the list of phone numbers will appear
Horizontal Arrangement	Screen Arrangement	HorizontalArrangement1	To organize the add and remove buttons (pickers) horizontally
PhoneNumberPicker	Social	PhoneNumberPicker1	Allow user to choose from numbers in contact list
ListPicker	Basic	RemoveListPicker	Allow user to remove number from phone numbers in group
TinyDB	Basic	TinyDB1	For storing and retrieving group's phone numbers from database

Set the properties of the components in the following way:

Set the Hint of MessageText to "enter a message"
Set the Text of TextGroupButton to "Text Group"
Set the Text of StatusLabel to "status".
Set the Text of GroupHeadingLabel to "-- Group -- ".
Set the Text of MembersLabel to "members will appear here".
Set the Text of PhoneNumberPicker1 to "Add Member".
Set the Text of RemoverListPicker to "Remove Member"

Add behaviors to the components

If you completed Text Group, Part I, you should have the following list defined in the Blocks Editor:

For this app, you still want the list but you don't want any pre-defined numbers in it-- the numbers will be added by the end-user of the app. So remove the text blocks with the numbers and leave the make a list block empty:

You'll need to add the following behaviors:

When the user clicks the "Add Member" button (the button associated with the PhoneNumberPicker), the picker will appear for the user to choose a number. When the choice is made, the app will add the chosen number to the PhoneNumbers list and update the database.
When the user clicks the "Remove Member" button (the button associated with the RemovListPicker), the picker will appear for the user to choose one of the numbers already in PhoneNumbers. When the choice is made, the app will remove the number from the list and update the database.
When the app begins, the numbers stored in the database are retrieved and loaded into PhoneNumbers.

Adding a Phone Number (Member) to the Group

The list of phone numbers in the contact list will appear when the user clicks the PhoneNumberPicker 's associated button: that behavior is built-in to the component. When the user makes a choice from the contact list, PhoneNumberPicker 's AfterPicking event is triggered-- your job is to program this to add the chosen item to the list and update the database.

You'll need the following blocks:

Block type	Drawer	Purpose
PhoneNumberPicker1.AfterPicking	PhoneNumberPicker1	The event-handler that is triggered when user chooses from contact list
add items to list	Lists	Your goal is to add chosen number to list
global PhoneNumbers	My Definitions	Plug this into list slot of add items to list
PhoneNumberPicker1.PhoneNumber	PhoneNumberPicker1	This holds the chosen phone number, plug into item slot of add items to list
TinyDB1.StoreValue	TinyDB1	Since the list is updated, need to update the database
text ("textGroup")	Text	Plug this in as the tag of TinyDB1.StoreValue
global PhoneNumbers	My Definitions	Plug this in as the value of TinyDB1.StoreValue
set MembersLabel.Text to	MembersLabel	Display the list on the phone
global PhoneNumbers	My Definitions	plug into set MembersLabel.Text to

The blocks should look like this:

How the Blocks Work

When the user chooses from the PhoneListPicker, the PhoneListPicker1.AfterPicking event is triggered. A PhoneListPicker' s job is to put the user's choice in its PhoneNumber property, so the event-handler just calls add items to list to get that choice into the PhoneNumbers list.

PhoneNumbers is a variable, and variables are short-term memory that will disappear when the app is closed. Thus, after adding the item to the variable, TinyDB1.StoreValue block is used to copy that list to the database-- the phone's long-term memory. The data is tagged with "textGroup". Later, you'll use that tag to re-load the phone number list from the database each time the app is opened.

After updating the database, set MembersLabel.Text to is called to display the list. This is necessary because list variables are hidden from the user until they are placed in a visible component. Directly placing a list into a label is a rudimentary way of displaying a list-- the list will appear in the form: (111-1111 222-2222). In the next section, you'll program a more elegant list display.

Test the behavior. On the phone, click "Add Member" and choose a number from the list of contacts that appears. Does the number appear in the MembersLabel? Try adding additional numbers to see how the list is displayed.

Displaying the List with Items on Separate Lines

At this point the app shows the user the phone numbers that have been added, but not very elegantly. Create a procedure displayMembers, which displays the list with each phone number on a separate line. Be sure and call the procedure in the PhonePicker1.AfterPicking event, below the add items to list block, so that the updated list is displayed. The call to the procedure should replace the blocks that set the MembersLabel.Text directly to the list. For help displaying the list on separate lines, see Displaying a List.

You'll need the following blocks:

Block type	Drawer	Purpose
procedure ("displayMembers")	Definitions	Create a procedure as you'll want to call this from multiple places
set MembersLabel.Text to	MembersLabel	Display the list here
text ("")	Text	Start the text out empty
foreach	Control	Iterate through the numbers
name number	in the foreach	Name the foreach variable "number". This is the current item of the foreach
global PhoneNumbers	My Definitions	Plug into in list slot of foreach
set MembersLabel.Text to	MembersLabel	Modify with each of the numbers
make text	Text	Build a text object from multiple parts
MembersLabel.Text	MembersLabel	Add to the label on each iteration of foreach
text ("\n")	Text	Newline character so that next number is on next line
value number	My Definitions	The current number from the list

Here's how the blocks should look:

How the Blocks Work

The foreach in displayMembers successively adds a phone number to the end of the label, placing a newline character in between each item.

Of course this procedure will not do anything unless you call it: you should add a call to the procedure in the PhonePicker1.AfterPicking event, below the add items to list block. The call displayMembers block can be found in My Definitions, and it should replace the blocks that directly set the MembersLabel.Text in the list.

Test the behavior. On the phone, click "Add Member" to choose another number to add to the list. When the modified list is displayed, does each number appear on separate lines?

Removing a Number from the list

To allow the user to remove a number from the list, you must first get the PhoneNumbers list into the RemoveListPicker that appears when the user clicks "Remove Member". Unlike the PhonePicker component, which gets its data from the phone's contact list, ListPicker requires you to explicilty load the items that will appear. You can do this by setting the Elements property of the ListPicker component. You do this within the RemoveListPicker.BeforePicking event, which is triggered right when the user clicks the button but before the list is shown.

The blocks should look like this:

Next, code the RemoveListPicker.AfterPicking event so that the user's choice is removed from the PhoneNumbers list. You'll need the following blocks:

Block type	Drawer	Purpose
RemoveListPicker.AfterPicking	RemoveListPicker	This is triggered after the user chooses a number from the list
remove list item	Lists	Removes the indexth item in a given list
global PhoneNumbers	My Definitions	Plug into list slot of remove list item
position in list	Lists	Given an item in a list, this gives you its index
RemoveListPicker.Selection	RemoveListPicker	The number chosen by the user, plug into thing slot of position in list
global PhoneNumbers	My Definitions	Plug into list slot of position in list
call displayMembers	My Definitions	Once the user removes one, display the modified list

The blocks should look like this:

How the Blocks Work

When the user chooses a number from the RemoveListPicker, the AfterPicking event is triggered. The event-handler uses position in list to get the index of the chosen number, then uses that index to remove the number from the list PhoneNumbers. The database is then updated and the list displayed.

Test the behavior. On the phone, click "Remove Member" and choose a number from the list that appears. When the list is re-displayed, is the number you chose gone?

Loading the List from the Database

The app so far works, and when changes are made to the PhoneNumbers list they are also stored in a database. Now you just need to add the behavior such that the data stored in the database is loaded when the app launches.

Program the Screen1.Initialize event-handler so that the saved list of phone numbers is retrieved from the database and placed in the PhoneNumbers list and the display is updated to show the list. You'll need to check the retrieved data to make sure there's something there-- after all, the first time the app is used, the database will not have any numbers in it.

You'll need the following blocks:

Block type	Drawer	Purpose
def variable ("valueFromDB")	Definitions	A temporary variable to hold the retrieved data
text (blank)	Text	Initial value for the variable can be anything
Screen1.Initialize	Screen1	This is triggered when app begins
set valueFromDB to	My Definitions	You'll set the variable to the value retrieved from db
TinyDB1.GetValue	TinyDB1	Get the stored response text from the database
text ("textGroup")	Text	Plug into tag slot of GetValue, make sure text is same as was used in StoreValue above
if test	Control	To ask if the retrieved value has some text
is list?	Text	Check if the data returned is a list (if no data is returned, this will be false)
global valueFromDB (x2)	My Definitions	This variable holds the value retrieved from GetValue
set PhoneNumbers to	PhoneNumbers	If we retrieved something, place it in PhoneNumbers

The blocks should look like this:

How the Blocks Work

When the app begins, the Screen1.Initialize event is triggered. The event-handler queries the database with GetValue and the tag "textGroup". If there is a value with that tag in the database, its corresponding value will be placed in the variable valueFromDB. The event-handler checks this value-- is it a list?-- and if it is puts the list into the variable PhoneNumbers and calls displayMembers.

Test the app. To test the final app, first package and install it on the phone and run it. Live testing won't work in this case because every time you "Restart App", in clears the phone's database: even if you've stored some data persistently, it is cleared when you restart the app. 

Click Restart App so that the app re-initializes. Does the list of numbers you've entered appear on reload? Try removing all items and testing again. Does the app launch without error?

Text Group Part II, Final Program

Variations

Once you get the Text Group app working, you might want to explore some variations. For example,

Write a version that records both the contact name and phone number of each member of the group. You can also use ContactPicker to let the user choose from a contact name instead of a number.
Write a version that allows the user to define and make use of multiple groups. You'll need a group list in which each item is a list of contacts/numbers, and you'll need a more complex user interface.

Review

Here are some of the ideas covered in this tutorial:

PhoneListPicker allow the user to choose from the phone numbers of his contacts. The choice is placed in the Selection property and the AfterPicking event is called when the user makes a choice.
ListPicker is similar to PhoneListPicker but it displays a programmer-defined list, e.g., the list of phone numbers in the group. You define the list that will appear in the ListPicker by setting the Elements property, and you can do this in the BeforePicking event. The user's choice is placed in the Selection property, and the AfterPicking event is triggered when the user makes a choice.
TinyDB is used to store data persistently so that it can be loaded each time an app begins. StoreValue stores with a tag to identify the data and the data itself (the value). GetValue returns the data for a given tag. Often, an app will call GetValue when the app begins (Screen1.Initialize) to load the persistent data.
Currently, App Inventor does not provide full access and functionality for the contacts and groups of the phone. In this tutorial, you created your own group and app for processing the group (adding,removing, and texting all).

Scan the Sample App to your Phone

Scan the following barcode onto your phone to install and run the sample app.

Or download the apk

Download Source Code

If you'd like to work with this sample in App Inventor, download the source code to your computer, then open App Inventor, go to the My Projects page, and choose More Actions | Upload Source.

MIT and Google are grateful to Professor David Wolber, CS Professor at The University of San Francisco, for developing this tutorial.

Done with TextGroup Part 2? Return to the other tutorials here.

Tutorial Version:

App Inventor 1

Tutorial Difficulty:

Advanced

Tutorial Type:

TextGroup

aaron — Fri, 14 Jun 2013 16:12:11 +0000

TextGroup

What you're building

This tutorial introduces the Texting component for sending and processing SMS text messages.You'll build an app that texts a message to a list of phone numbers. This tutorial assumes you are familiar with the basics of App Inventor: using the Component Designer to build a user interface, and using the Blocks Editor to specify event handlers. If you are not familiar with the basics, try stepping through some of the basic tutorials before continuing.

Getting started

Connect to the App Inventor web site and start a new project. Name it TextGroup, and also set the screen's Title to "TextGroup." Open the Blocks Editor and connect to the phone.

Introduction

You'll design the TextGroup app so that clicking on a button texts a message to a list of phone numbers. The app introduces the following App Inventor concepts:

The Texting component for sending texts and processing SMS texts.
List variables to keep track of the numbers to text.
The Timer block for repeating operations on a list of data (the list of phone numbers)

Set up the components

The user interface for TextGroup is simple: it has a text box for entering the message to send, a button to send the message, a label that reports when the message is sent, and a Texting component. Use the Component Designer to create this interface. When you finish, it should look something like the snapshot below (there are also more detailed instructions below the snapshot).

The following table describes the components you need. Drag each component from the Palette into the Viewer and name it as specified below:

Component Type	Palette Group	What you'll name it	Purpose of Component
TextBox	Basic	MessageText	User will enter message here
Button	Basic	TextGroupButton	User will click here after entering the message
Label	Basic	StatusLabel	Reports when texts have been sent
Texting	Social	Texting1	The component that sends the texts
Clock	Basic	Clock1	Used to designate when to send the texts

Set the properties of the components in the following way:

Set the the Hint of MessageText to "enter a message"
Set the Text of TextGroupButton to "Text Group"
Set the Text of StatusLabel to "status"
Set the TimerEnabled of Clock1 to "false"

Add behaviors to the components

TextGroup's behavior is as follows: when the user clicks the TextGroupButton, the app should text the message entered by the user in MessageText to all the numbers in a list of phone numbers. When all are sent, it should report the last message sent in the StatusLabel.

Text the entered message to one phone number.

To introduce yourself to the Texting component, begin by creating a simplified version that texts the message entered by the user to your own phone. To send a text, you need to set two properties of the Texting component: the PhoneNumber and the Message. Once these properties are set, you call the SendMessage function to actually send the text.

Open the Blocks Editor and drag out the following blocks:

Block Type	Drawer	Purpose
TextGroupButton.Click	TextGroupButton	When the user clicks the button, this event handler is triggered.
set Texting1.Message to	Texting1	Set the Message property before sending
MessageText.Text	MessageText	This is the message the user has entered.
set Texting1.PhoneNumber to	Texting1	Set the PhoneNumber property before sending
text ("1112222")	Text	Put your own phone number as the text.
Texting1.SendMessage	Texting1	Send the message

The blocks should look like this (but with a real phone number instead of "1112222")

How the blocks work

When the user clicks the TextGroupButton, the event-handler is triggered. The first row of blocks gets the text entered by the user (MessageText.Text) and places it into the Message property of the Texting1 component. The second row of blocks sets the PhoneNumber property of the Texting1 component. After the first two rows of blocks, Texting1 knows what to send and who to send it to; the last block just instructs Texting1 to actually send the message.

Test this behavior. If your phone is connected, the app should appear with the MessageText box and button. Enter a message and click on the TextGroupButton. Does the text get sent? Check your phone (or the phone you sent the text to) to see.

Texting a list

Next, you'll modify the blocks to text more than one number at a time. You'll first define a global variable to store the data for the app: the phone numbers. Global variables are not seen by the user; they are the app's "hidden" memory. In this case, you'll define the list of phone numbers to which the text is sent.

You'll need the following blocks to build a list of phone numbers:

Block Type	Drawer	Purpose
def variable	Definitions	Defines the PhoneNumbers variable (rename it)
make a list	Lists	Used to define the items of the list
text (3)	Text	The actual phone numbers

The blocks should look like this, but with two or three phone numbers of your friends.

Note that text blocks are used for the phone numbers, not number blocks. This will allow for dashes, which are not allowed in number blocks. number blocks are used for data on which you want to perform mathematical computations.

Now you're ready to modify the TextGroupButton event-handler so that it texts each number in the variable PhoneNumbers.

You'll need to set up a timer to send a text message to each number in the list.

A timer performs some action each time the clock ticks. To
control the timer, define a global variable named nTicks. We will set this variable initially to the number of phone numbers in the
list.  And then we will subtract 1 from the variable each time we send a message. 

A timer is done in two parts.  In TextGroupButton.Click
we will no longer send the message. Instead, we will initialize the global nTicks variable to the length of
the phoneNumbers list.  And we will enable the Clock1.

The second part is done using a Clock1.Timer block. This block will contain the Texting1.SendMessage
command. Each time the clock ticks the following steps will be performed:

Select a number from the phoneNumbers list using the nTicks as the index.
Set the Texting1.PhoneNumber to the selected number.
Send the text message using Texting1.SendMessage.
Subtract 1 from the nTicks variable.
If the nTicks is less than or equal to 0, disable the clock

Reconfigure the Clock.Timer block so it looks like this:

Reconfigure the TextGroupButton.Click block so it looks like this:

How the blocks work

When the TextGroupButton is clicked, the Texting1.Message property is set to the message entered by the user in MessageText. Then the nTicks variable is set to the length of the phoneNumbers list and the Clock1.TimerEnabled is set to true. This will start the clock ticking. Then in the Clock1.Timer block, the message will be sent to the target phone number and the global variable nTicks will be decremented by 1. The clock will continue ticking and sending messages until nTicks at which point the Clock1.TimerEnabled will be set to false thereby stopping the timer.

Test the behavior. Click the TextGroupButton on the phone. Is the text sent to all the numbers in the list?

Reporting the Status of the app

It's always a good idea to give the user feedback when they initiate an operation. In the app you've built thus far, the user clicks on the TextGroupButton and nothing changes in the app's user interface. Though the user might hear the phone's chime for transmitting the text, it's still better to report a status directly in the app.

Modify the blocks so that the status label reports the last message sent. You'll need the following blocks:

Block Type	Drawer	Purpose
set StatusLabel.Text to	StatusLabel	This is where status will appear
join	Text	To concatenate the two parts of the status message
text	Text	Put "last message sent:" in this text block
MessageText.Text	MessageText	The message just sent

The updated Clock1.Timer blocks should look like this:

How the blocks work

The join block is used to concatenate two pieces of text. You need it when you want to join data from a variable or property with some other text. If you want to piece together more than two texts, there is also a make text block.

Test the status behavior. Does the status message report the message that was sent?

Final program

TextGroup, Final Version

Variations

Once you get the TextGroup app working, you might want to explore some variations. For example,

Write a "random date" version that randomly chooses a number in the list to call. You won't need a Clock.Timer block, but you will need the pick random item function in the Lists drawer.
Write a version in which "Missing You" is sent to the list of numbers as soon as the app begins (on the Screen.Initialize event). This will allow for quick texting without clicking an additional button.
Write a version that allows the user to enter the numbers in the list. This way you don't need to re-program the blocks to change the group you are texting and your app can be used by others! You'll need to use TinyDB to store the numbers after they are entered.

Review

Here are some of the ideas covered in this tutorial:

Instead of placing data directly in event handlers, you can create list variables and program event handlers to process the list.
An app can repeat functions on all items of a list using the Clock.Timer block.

Scan the Sample App to your Phone

Scan the following barcode onto your phone to install and run the sample app.

Or download the apk

Download Source Code

If you'd like to work with this sample in App Inventor, download the source code to your computer, then open App Inventor, go to the My Projects page, and choose More Actions | Upload Source.

MIT and Google are grateful to Professor David Wolber, CS Professor at The University of San Francisco, for developing this tutorial.

Done with TextGroup? Return to the other tutorials here.