1. Getting started with the Arxterra software and 3DoT Firmware
By Christopher hirunthanakorn
5/23/16

2. What does the Arxterra Software and 3DoT Firmware Include?
Arduino code that is running on the 3DoT Board.
Mission ready out of the box!
ArxRobot iPhone and Android App
Smartphone app that communicates with the 3DoT Board to control your robot.
Can be used as the controller or as the link to the Arxterra Control Panel.
Arxterra Control Panel
Website that allows users to pilot any robot that is configured in community mode.
Has more customization than the ArxRobot App in terms of data that can be received or commands that can be sent.

3. Arduino IDE Very easy to use and learn.
Lots of documentation and examples to look at.
Requires some setup for programming the 3DoT Board.
fio-v3-hookup-guide#installing-windows

4. setup for programming the 3DoT Board. Part 1
Begin by downloading the Robot3DoTBoard located here.
Place the Robot3DoTBoard folder into your Arduino library folder.
Inside the Robot3DoTBoard folder you will find an “examples” folder. Review the sample projects located inside this folder, for a similar project. Here is the Robot_3DoT_Basic project that comes pre-installed.
Place the selected folder in your Arduino project folder and launch the Arduino IDE.
Compile your program and verify that it runs without errors.

5. setup for programming the 3DoT Board. Part 2
Place the Robot3DoTBoard folder into your Arduino library folder.
Inside the Robot3DoTBoard folder you will find an “src” folder. Cut and Paste the “Configure.h” file from this folder into your project folder.
Again, launch the Arduino IDE and verify that it compiles without errors.
When debugging your program set DEBUG and ECHO_COMMANDS to TRUE. Once your code is bug free, to avoid latency errors and minimize bandwidth set values back to FALSE.
That’s it! From now on development is done within the user friendly Arduino IDE.

6. Adding Custom Commands Step 1: Assign new command mnemonics ID numbers.
In our example we will be adding 3 custom commands named MOVE, BLINK, and SERVO.
The MOVE command mnemonic ID 0x01 is already defined in Configure.h
This predefined MOVE command is intercepted and our robot unique code is to be run instead.
The next two commands BLINK and SERVO are new and assigned to the first two addresses in the custom command address space 0x40 - 0x5F.
Finally, the constant CMD_LIST_SIZE is set to the total number of user defined commands.

7. Adding Custom Commands Step 2: Register commands by linking IDs to their corresponding command handlers
In our example when the MOVE command is intercepted the moveHandler is to be run. In a similar fashion the BLINK command calls the blinkHandler and SERVO the servoHandler.
Step 3: Tell 3DoT Robot software about new commands
Finally, the onCommand list of commands and associated handlers, are registered with Robot3DoT.
That’s it! Now write your command handler as you would any other Arduino script. Don’t worry in the next slide I will show you how.

8. Writing a Custom Command handler
At right, is a test of a SERVO command handler.
All command handlers include three parameters.
The first parameter, cmd is simply the command id. For our example 0x41.
The second parameter, param[]is a list of the parameters needed to implement the command.
For our example, only the servo angle is sent.
The third parameter, n is the number of parameters sent. For our example only 1.

9. Command Code Example

10. Arxterra Firmware – Configure.h
The Configure header file has 5 major subsections:
Flags
Pinouts
Command IDs
Telemetry IDs
Error Codes
The Flags settings allow you to configure the code for testing or normal operation.
Pinouts are defined for the 3DoT board. They may be modified if the Robot3DoTBoard library is used with another Arduino board, like the Leonardo.

11. Arxterra Firmware – Configure.h
The Configure header file has 5 major subsections:
Flags
Pinouts
Command IDs
Telemetry IDs
Error Codes
The Command IDs listed are predefined. The 32 possible Custom Command IDs 0x40 - 0x5F, may be added to the end of the table based on the unique requirements of your robot.

12. Arxterra Firmware – Configure.h
The Configure header file has 5 major subsections:
Flags
Pinouts
Command IDs
Telemetry IDs
Error Codes
The Telemetry IDs listed are predefined. Custom Telemetry IDs are in development. Until then, repurpose an existing one.

13. Arxterra Firmware – Configure.h
The Configure header file has 5 major subsections:
Flags
Pinouts
Command IDs
Telemetry IDs
Error Codes
There are two (2) types of error messages:
Exception
Emergency
Exceptions originate from the command decoder and indicate a problem with a received command. These “exception” codes are shown at right.
Emergencies indicate a more serious problem with the robot. As shown at right, only one type of emergency has been identified.

14. Adding a Custom Telemetry Channel Step 1: Instantiate Packet
In our example we simulate a current sensor wired to MOTOR 2.
MOTOR2_CURRENT_ID is defined as 0x02 in Configure.h
To simulate the data stream coming from the sensor we will read ATmega32U4 Register OCR4D which controls the duty cycle of MOTOR 2.

15. Adding a Custom Telemetry Channel Step 2: Modify default values – Optional –
Before a packet is created and sent, it is qualified.
Specifically, the data in a packet must change by some amount from the previous packet and may not be sent with a period less than some value. In most cases you can leave these values at their default values.
Change in Sensor reading of more than +/-2 DN.
Sample period > 1 second
In the code shown the accuracy of the sensor reading is improved to +/- 1 DN, while the maximum sample period is decreased to 500 msec (frequency increased to 2 Hz).

16. Adding a Custom Telemetry Channel Step 3: Read sensor and send packet
To simulate the data stream coming from the sensor we will read ATmega32U4 Register OCR4D which controls the duty cycle of MOTOR 2.
This code segment uses the preprocessor conditional directives #if to make sure that an MCU with a ATmega32U4 or ATmega16U4 is selected under Tools > Board.

17. Arxterra Firmware continued
Arxterra_firmware tab
Contains the main loop of the code.
Default setup is to check for commands sent and send telemetry back but can be configured according to your robots specifications.
Command tab
Contains the commanddecoder and commandhandler functions
Custom commands and changes to how commands are executed for your robot will be put into the commandhandler function.
Pinouts_robot.h and battery_selector tab
Contains all of the pin definitions and global variables to be used.
Contains the list of command ids and telemetry ids. Any custom commands or telemetry will have their id added here.
Telemetry tab
Contains the code that collects all of the data that needs to be sent back to the ArxRobot App or Control Panel.
Additional Tabs can be added to organize your code appropriately.