Wandering Ambassador Software Manual

Wandering Ambassador Software Manual

Written by: Armando Briones

NOTE: START HERE IF YOU WANT TO KNOW HOW THE ROBOT WORKS AND TO UNDERSTAND WHAT CAN BE DONE GIVEN ITS CURRENT STATE.

Note: Pandaboard and PSoC Manuals are on P13215’s Edge page under: /public/Documents/SoftwareManual

The Wandering Ambassador software is split in three different parts:

1)Core software written in C for the PSoC 5 development board

2)Server code written in Python for the Pandaboard

3)Web application software written in HTML/CSS/JavaScript/JQuery

This document explains how the software works and how the devices are connected. This document will also be split in multiple sections describing the different modules in this system.

Part 1The devices

There are two devices running software in this project:

PSoC 5 – A Cypress development kit that uses one of their micro controllers. This board includes different modules for testing the chip on board.

Pandaboard – A board produced by Texas Instruments that can run Ubuntu. This board has several ports for transmitting/receiving signals, mostly using as a media board.

The robot runs on these two boards. One could say they are the brains. The motors are powered by the PCB, which I will not describe in detail unless needed. The PCB also distributes the power required for these boards. But the brain of the robot is contained between these two boards.

Part 2How are they connected?

The following diagram shows the connection between the devices.

The wandering ambassador can be controlled in two ways: the web application and an optional RC controller. The web application, however, doesn’t only allow the user to move the robot, but it also provides extra modes of motion and the ability to see the current sensor readings.

Brief description of operation:

1)The client block is in essence the website through which one sends commands.

2)The Pandaboard is used in this project as a simple server written in Python. This server serves the website to any client with the correct credentials. The Pandaboard decodes the instructions sent by the website and connects Serially with the PSoC board.

3)The PSoC board receives the instructions from the Pandaboard and accordingly sends digital signals to the H-Bridge in the PCB to move the motors, read the sensors etc. Sensors also use analog signals.

4)The PSoC board replies with readings or other useful information or simply executes the commands.

5)The Pandaboard receives the response from the PSoC board and returns data to the website where values are updated or control is returned to the user.

Part 3 The Core code (PSoC section)

The PCB needs to receive different kinds of signals to control the motors and other parts like the encoders.

The Cypress board (PSoC 5) runs C code and uses low-level instructions to process relevant data. Using PSoC Creator, a development environment, one has access to all the components in the board.

Selecting parts to use is as simple as dragging and dropping parts from the library onto the workspace. The following diagram shows the components as viewed from PSoC Creator.

PSoC Creator produces headers and source files for each of the components. These are useful for accessing functionality of the parts, but the code that runs them must be custom made. In the following parts I will describe the different source/header pairs created for this one project.

In the picture above one can see the timer modules used to measure different spans of time. See MotorFunctions.c for more insight into the uses.

The ADC module transforms the analog signals coming from the encoders (not efficiently implemented) and the sonar signals.

There are two UART modules; the one on the left is used to receive instructions and to transmit the responses. The one on the right would ideally be used to receive the sonar readings. See potential changes*

Part 3.1 Interrupts

Some component in the high-level diagram support interrupts. One key difference between the redesign of the software was the use thereof. All relevant components in the design use interrupts except for the pins.

Part 3.2Serial communication

The PSoC was programmed to use 4-byte instructions. The code in the Pandaboard is set up to transmit instructions with up to 4 characters. These have descriptive names and will be described when necessary.

The UART module in the design receives the instructions through interrupts and then stores the address of the function to be executed in a function pointer set up in main. The main continuously loops until there is a pending instruction (set up in the interrupt code).

Part 3.3 Pins

In the design there are unconnected output pins. These pins are used to transmit signals to the H-bridge, and to enable/disable the sonars.

See SonarFunctions.c and MotorFunctions.c for the available options.

Part 3.4 UML Diagrams

Each module in the system contains functions to use the related devices. The following is a breakdown of the Header/Source pairs written for WAMB. The full implementation of the code can be found in the project.

All functions are self-descriptive. To understand what pins are modified and how motion or sensing is actually implemented refer to the project.

All important constants and global variables are stored in AmbassadorCommands.h. The code in isr_1.c is responsible for translating received commands and executing the instructions above.

See the next section for more detail.

Part 4 PSoC Logic Flow (IMPORTANT)

All software in this project (except for the code generated by PSoC creator) is custom. And the flow of logic was designed by me ( :D ). The following is a description of how things work. It’s important to understand this if you want to expand it or if you want to dispose of it (in which case you can use this as a reference of how to use the different modules).

The software in the PSoC is initialized through the Main. In the main all interrupts are set up, enabled and all local variables and core modules are initialized.

In the main, there are two function pointers (declared as extern variables in AmbassadorCommands.h) used to store pending instructions.

Once all modules are set up main jumps into an infinite loop where the system checks if there exist an instruction pending execution.

But how do these instructions work?

As mentioned beforehand, the PSoC receives requests from the Pandaboard. These instructions are received through the serial port and are stored byte-by-byte in an array called “command” inside “isr1.c.” Whenever 4 characters are received, the characters are compared against the available instructions.

There are three kinds of instructions:

1)Instructions that should be performed as soon as received

2)Instructions that can wait to be performed without parameters

3)Instructions that can wait to be performed with parameters

All instructions can either produce a response or simply execute without replying.

When the interrupt code detects a valid sequence of characters the type of instruction is determined and the address of the instruction is stored in one of the function pointers. If the system is currently executing an instruction the new instruction is simply stored. When the resources are available the loop will identify the status of the “pending” variable as true and then proceed to execute it.

What are the available instructions?

Each instruction is stored in the source file that it relates to. The following is a breakdown of the different instructions and their uses

In similar fashion one can add more instructions and assign functionality to them.

Read the whole document to get a clue at how to do it or simply trace the steps from isr_1.c.

Part 5 Pandaboard / Server

The server is implemented in a single file called “wambServer.py” During execution, the server runs indefinitely waiting for requests.

This code understands all the instructions listed above as well as other values used to translate between request from the website and the PSoC instructions.

The flow is simply

Modifying this code requires the use of python. For now all this does is to serve the website and transmit information.

See “Running a session” at the end of the document.

Part 6 The GUI

The controller itself is a website.

Special care was taken to make it intuitive. In the left panel of the first image we have an accordion with options used for navigation purposes.

Modes of operation will be explained later, but they are controlled through this menu.

The middle section shows the directional pad. To use, simply hover over the direction you want the robot to move and it will happen. To stop the robot press stop.

The second tab shows the current sensor information (updated every 3 seconds) and pressing the update button will send a request to the Pandaboard to update the sensor reading.

The GUI was written using HTML, CSS, Javascript and JQuery. The following is a listing of the different modules created to allow this functionality.

Brief Description of the GUI code:

1)The HTML contains the general layout of the different modules

2)The tabbing and accordion modules were added by using the JQuery UI libraries. See their tutorials to learn how to modify them and/or to find alternatives

3)All buttons and modules are event driven. An additional JQuery library was linked to allow touch events. This site can be accessed through any mobile device with a browser.

4)On click/touch events one of many scripts are invoked.

5)The scripts written decipher what action should be taken based on the button pressed and using the functions in ajax.js POSTs requests to the server.

6)Upon receiving a response from the server (Pandaboard) the JQuery scripts update relevant modules on screen.

Part 7 JQuery Scripts

Each major module on screen was managed through their own script. The following is a list of the major modules and a brief description.

Motion.js – Scripts used to react to the push of a D-pad button and/or the Stop button.

Sensors.js – Scripts used to determine what sensor should be updated. On push of the update button the sonar instructions listed above are sent to the Pandaboard.

TimerFunctions.js – The scripts in this file are used to periodically send sensor requests to the Pandaboard (every 1.5 s).

UtilityFunctions.js – The scripts in this file keep a history of the buttons pressed and populate one div in the accordion.

Controls.js – The scripts in this file are responsible for toggling the command modes and the timing of the motion requests.

ajax.js – This is the file with the scripts in charge of sending requests to the server. Most source file above use the functions in this file.

See the code itself to figure out how it works. Reading the code and this file should be sufficient to help you get started.

Control Modes

There are two main control modes. “Continuous” and “Execute and halt.” Continuous execution allows the user to immediately switch from instruction to instruction without having to stop the execution of the current instruction.

The second option executes one instruction for as long as the slider values show.

Part 8 Running a session

The username and password for administrator rights are the same: “wamb”

1)Turn robot on, make sure all boards are connected properly

2)Using putty or another ssh tool access “wamb.student.rit.edu“

3)If that doesn’t work it means that the name server is not working properly. This cannot be fixed manually, and the easiest workaround is to connect the Lilliput monitor to the Pandaboard and a mouse. Run “ifconfig” to find the IP address of the board and use that to access the board remotely through Putty.

4)With access to the board navigate to the “WambScript” folder.

5)Before continuing make sure that the USB-Serial connector is properly connected to the Pandaboard. If connected, using the command line and run the command “ ls /dev/ttyUSB* ” to find out what the port name of the USB connector is. It should default to ttyUSB0 if nothing else is connected, but this is not always the case. If this is not the case search around about how to use the serial number of your USB-Serial connector (you get this by running “lsusb”) to mount it.

6)Once you know the name of the port, and depending on your results from the previous step. Do the following:

A) Regardless of the name run the command “sudochmod 0777 /dev/[name of your usb connector]”

Enter the required credentials

B) If the name is ttyUSB0 simply run the command “python wambServer.py” this will start the server code.

C) If the name is something different open “wambServer.py” through vi and change the port name to match yours. then run “python wambServer.py”

7)Using a browser send a request to the server. Use an URL like

wamb.student.rit.edu:8090

or

ip-address:8090

This will load the website.

8) The credentials for using the site are both “test”

9)Use the website to send any command you wish

10)Enjoy

Also, make sure that the locks for the wheels are released.

Where to go from here?

There are several possibilities. One could re-do the code too, but if this system is kept (trust me, it’s functional, good, and you don’t want to go through what I went) the following are potential changes.

1)Get new sensors, the sonars are incredibly impresise, and the PSoC has timing problems decoding periodic signals. I could’ve used the serial reading from the sonars (in fact it’s all set up in the second UART module), but the PSoC needs to be calibrated to match the timing. Either fix this (waste your time) or get new sensors with better performance.

2)Finish implementing the website. At the moment two tabs are active. Add more stuff to the other tabs

3)Whatever the sensors you use are, instead of having the requests be sent by the website have them set up as a thread in the python code. If you do this, find a way to transmit this to the site (good luck).

4)Add a button or an option to enable/disable the periodic sensor readings

5)Add more instructions to the PSoC code.

6)Integrate the encoders (already coded and implemented, but commented out because they weren’t fully tested). Currently we’re using timers to stop the motion. This is battery dependant, which is not always a good thing.

7)Make the function pointers arrays of function pointers so that several instructions can be queued. That way you should be able to dispose of instructions you could skip (read sonars) and give way to more important ones (stop, move etc).

8)Either use a different media board, or learn to use its serial port to have serial to serial connections (I tried it from Pandaboard side to hyperterminal and it worked, and I tried PSoC to hyperterminal and it also worked, but when connecting both through a serial cable the PSoC couldn’t understand anything; this is not a baud rate issue).

9)Maybe learn to use the Ethernet or other parts of the Pandaboard.

10) Use Pic microcontrollers to add additional functionality

11)Have a dedicated Sensor board because the PSoC can’t perform very well when overwhelmed by many instructions at once.

If you have any questions feel free to send me an email to :