Maintenance Manual

User Manual:

Open the PDF directly: View PDF .
Page Count: 21

Download
Open PDF In Browser	View PDF

SimuCopter Maintenance Manual
Version 1.0a

MAINTENANCE
MANUAL

SimuCopter Maintenance Manual
Version 1.0a

Table of Contents
Table of Contents

Installation
Prerequisites
Installing SimuCopter

4
4
4

Creating a Flight Mode Diagram
Creating from a template (recommended)
Creating from scratch

5
5
5

Switching ArduPilot Modes (SITL / NAVIO)

Adding Simulink Blocks
Simulink
SimuCopter - Client Side
SimuCopter - ArduPilot Side
SimuCopter - SITL Side

10
10
13
14
14

Troubleshooting
Logs & progress
Agent shutdown / killall
Problem: Segmentation fault on arducopter start (NAVIO mode)

15
15
15
15

System Architecture
General
SimuCopter Integration Points
Communication

17
17
18
19

Caveats
Simulink shutdown quirks
Sporadic segmentation faults
Missing C++ library files in certain Simulink models
define private public
Message serialization - hardcoded buffers
No Simulink independence

21
21
21
22
22
22
22

SimuCopter Maintenance Manual
Version 1.0a

Installation
Prerequisites
● EMLID Real-Time Linux Image (or Raspbian for testing purposes)
● MATLAB 2015 or later with Simulink

Installing SimuCopter
Step 1: Clone the repository onto the Raspberry Pi
/home/pi$ git clone https://github.com/icedraco/simucopter-bridge.git

Step 2: Run the installer script on the Raspberry Pi
/home/pi$ cd simucopter-bridge
/home/pi/simucopter-bridge$ bash install.sh
...

The installer script will automatically check for the presence of ardupilot and offer to download it if
missing. The script will also augment said ardupilot installation to work with the SimuCopter system.
Step 3: Download simucopter-matlab onto the PC/control station
The directory is a part of the simucopter-bridge repository and can be safely extracted from within it onto
the PC via an SCP file transfer. Be sure to do this AFTER you run the installer!
WINDOWS/Desktop$ scp pi@10.66.66.254:simucopter-bridge/simucopter-matlab ./

SimuCopter Maintenance Manual
Version 1.0a

Creating a Flight Mode Diagram
Creating from a template (recommended)
1.
2.
3.
4.

Locate the TEMPLATE.slx file in the simucopter-matlab directory.
Copy the TEMPLATE.slx file, then Paste it into the same location.
Rename the Copy of TEMPLATE.slx file into a flight mode.
Double-click the renamed SLX file to open a Simulink window, and
start designing your new flight mode diagram. The diagram should be
preconfigured to work with SimuCopter on a Raspberry Pi.

NOTE:
Be sure to check the Board Parameters in the Tools -> Options window:
● The correct IP and credentials should be set.
● The flight mode is deployed to SITL by default! If you need to use it
on physical hardware (navio), be sure to follow the instructions in the
NAVIO Mode section!

Creating from scratch
While it is much easier to use a template, in an event and the template file is damaged, or missing, the
following instructions will help you to reconstruct the template model.
Step 1: Create a blank Simulink model

SimuCopter Maintenance Manual
Version 1.0a

Step 2: Change execution mode to External

Step 3: Configure model
Click Tools -> Run on Target Hardware -> Prepare to run
to prepare, and open the Configuration Parameters
window.
Modify only the sections/settings mentioned below and
leave the rest as default, unless you have a reason not
to...

Section: Hardware Implementation

● Change Hardware board to be Raspberry Pi
● Configure Target Hardware Resources section below as follows:
○ Board Parameters:
■ Device Address: IP address of the Raspberry Pi (e.g.: 10.66.66.254)
■ Username:
username to log into (default: pi)
■ Password:
password to log in with (default: raspberry)
○ Build Options:
■ Build Action:
Build and run
■ Build directory: /home/pi/simucopter

SimuCopter Maintenance Manual
Version 1.0a

Section: Code Generation

● Language: C++
● Build configuration: Specify
○ Linker:
-lrt -lpthread -ldl -lzmq
○ C++ Linker: -lrt -lpthread -ldl -lzmq
Section: Code Generation / Custom Code

● Insert custom C code in generated:
○ Source file:
Nothing
○ Header file:
Nothing
○ Initialize function: simucopter_init();
○ Terminate function: simucopter_stop();
● Additional Build Information:
○ Include directories(space-separated):
simucopter bridge
○ Source files (space-separated):
simucopter-agent.cpp BridgeClient.cpp BridgeMessage.cpp
ZmqBridgeMessageSerializer.cpp AbstractBridgeCommandHandler.cpp
○ Libraries:
○ Defines:

Nothing
SIMULINK_AGENT
6

SimuCopter Maintenance Manual
Version 1.0a

Section: Code Generation / Interface

● Code interface packaging:

Nonreusable function

Any configuration not mentioned here can be left as-is.

NOTE
Don't mistake the Simulation Target section with Code Generation / Custom Code! Both sections
appear the same. However, the former is supposed to remain empty (unless you yourself have a reason
to reconfigure it) while the latter is to be configured as mentioned above!
At this point, you should have re-created the model template from the "Creating from a template" step.
You may proceed from there in creating your Flight Mode Diagram.

SimuCopter Maintenance Manual
Version 1.0a

Switching ArduPilot Modes (SITL / NAVIO)
The system can be configured to work in SITL (software-in-the-loop / "simulation") mode or in NAVIO
(hardware) mode.

NAVIO Mode
In short: define ARDUCOPTER_NAVIO in the Simulink model configuration
Procedure:
1. Click Tools → Run on Target Hardware → Options...

2. Select Code Generation / Custom Code
3. In Defines section, add the string: ARDUPILOT_NAVIO

SITL Mode
This mode is used by default. In order to return to it, undo the instructions for NAVIO mode above.
TIP: See simucopter-agent.cpp to understand how the two modes are activated.
NOTE
Switching between SITL and NAVIO modes requires a lengthy recompilation process of the ArduPilot
software! It may take several minutes for the first Simulink flight mode deployment to work!
You can monitor the progress of the compilation from the Raspberry Pi device by reading the log file of
the flight mode (the name is usually the same as the SLX filename):
pi$ tail -f ~/FlightModeName.log

SimuCopter Maintenance Manual
Version 1.0a

Adding Simulink Blocks
Simulink
Click the Block Library icon in a Simulink Model window

Add a user-defined function block to the model

Select the "User-Defined Functions" section in the Simulink Library Browser, and drag the MATLAB System
block onto the model window.

SimuCopter Maintenance Manual
Version 1.0a

Create a new .m file for the block

Use the BLOCK_TEMPLATE.m file to create the code that the new block is going to execute:
● Right-click the BLOCK_TEMPLATE.m file, select Copy, then paste into the same folder.
● Rename the new Copy of BLOCK_TEMPLATE.m file into the name of the block you are going to
create. For example: Copter_Get_Pitch.m if your block name is going to be Copter_Get_Pitch.
● Double-click the .m file in order to edit it.
● Change the classdef string to match the name of your block (e.g., from BLOCK_TEMPLATE into
Copter_Get_Pitch)
● Change the copter_get_???? string to the name of the C function that this block will execute. In our
case, we name it copter_get_pitch.
IMPORTANT
Code executed solely on the Raspberry Pi MUST be inside the "coder.target('Rtw')" if block! Failing to do
so will result in Simulink trying to compile locally (i.e., on Windows) code that does not exist!

Associate the block code file with the block itself
● Double-click the new block you've created to get the
Block Parameters dialog.
● Click the "Browse" (folder) button and select the
newly created Copter_Get_Pitch.m file inside.
● Click OK to associate the code with the block.

SimuCopter Maintenance Manual
Version 1.0a

Add the newly created block to the SimuCopter Block Library
● Locate and double-click the SimuCopterToolbox.slx file in the
left-hand file list; double-click it.
● Click the small "lock" icon in the bottom-left corner of the
window.
● Drag the newly created block from the model window into the SimuCopterToolbox window.
● Re-activate the lock and save changes.

At this point, you have created a Simulink block. However, you still need to add support for it in the
backend!

SimuCopter Maintenance Manual
Version 1.0a

SimuCopter - Client Side
You are now going to edit the files/code used by the client side of the SimuCopter system: the side that is
ran by the Simulink Agent executable. The files/code you are about to edit must be available to the
Simulink software on your PC (i.e., the simucopter-bridge/simucopter/ folder on Windows)!
simucopter.h
Add a declaration to the header file for the function you defined in the .m file. The name is the same as the
name in the string:
double copter_get_pitch();

simucopter-agent.cpp
Add a definition of the copter_get_pitch function that calls a corresponding method of the ArduPilot
Bridge Client:
double copter_get_pitch() {
return G_ARDUPILOT->get_pitch();
}

SimuCopterMessage.h
Add a new SimuCopterMessage ID:
GET_PITCH = 0x6666;

IMPORTANT: This file must be synchronized with the server side below!

SimulinkBridgeinterface.h
Add an inline method that requests a double from the SimuCopter server:
inline double get_pitch() { return m_client->request_double(SimuCopterMessage::GET_PITCH); };

SimuCopter Maintenance Manual
Version 1.0a

SimuCopter - ArduPilot Side
Now it's time to edit the files/code used by the server side of the SimuCopter system: the side that is ran
by ArduPilot. The files/code you are about to edit must be available to the ArduPilot software on the
Raspberry Pi!
ArduCopterRequestHandler.cpp
IMPORTANT
This file should only be edited if you are adding a getter/request block! Blocks that instruct ArduPilot to
do something (rather than simply fetch information) should go in the next file instead!
● In the register_self method, add a line that shows that you can handle the new GET_PITCH
message: service.set_request_handler(SimuCopterMessage::GET_PITCH, this);
● In the handle method add a case that handles the aforementioned command. See available code in
that file for an example.

ArduCopterCommandHandler.cpp
IMPORTANT
This file should only be edited if you are adding a setter/command block! Blocks that obtain information
from ArduPilot should go in the previous file instead and not this one!
● Edit the do_handle and handle functions, adding a case for the SimuCopterMessage::GET_PITCH
that handles this command. See available code in that file for an example.

SimuCopter - SITL Side
NOTE: SITL side only has a request handler! It does not yet support commands!
The procedure is very similar to adding a block to the ArduPilot side with the SitlRequestHandler.cpp file
being used instead of ArduCopterRequestHandler.cpp!

SimuCopter Maintenance Manual
Version 1.0a

Troubleshooting
Logs & progress
After the flight model is finished "Building" in Simulink, you can view the execution progress on the
Raspberry Pi device itself by reading/tail-ing the log file. The log file is normally kept in the home folder
(i.e., /home/pi) under the same name as the SLX file that's being activated.
Example
tail -f /home/pi/TestFlightMode.log

Agent shutdown / killall
If your Simulink is stuck, and you need to shut down the system in order to restart it, you need to kill all the
relevant processes still running on the Raspberry Pi. In order to do it, you must perform a kill command as
a root user, taking out both - the Simulink agent (if still running), and ArduPilot executable.
Use the following commands to do so:
sudo -i
ps -ef | grep "\.elf -port" | grep -v grep | awk '{print $2}' | xargs kill -9
ps -ef | grep copter | grep -v grep | awk '{print $2}' | xargs kill -9

You may want to put these commands in a script, as it isn't rare for such measures to be needed from time
to time.

Problem: Segmentation fault on arducopter start (NAVIO mode)
This usually happens if ArduCopter was not launched as root. Use sudo in order to launch ArduCopter
instead: sudo ~/ardupilot/build/navio/bin/arducopter -C /dev/ttyAMA0 -A tcp:0.0.0.0:5760
THIS IS NOT THE PROBLEM WITH SPORADIC SEGMENTATION FAULTS AFTER THE STARTUP STAGE! SEE
CAVEATS SECTION FOR THE MORE NASTY ISSUE.

SimuCopter Maintenance Manual
Version 1.0a

TECHNICAL
MANUAL

SimuCopter Maintenance Manual
Version 1.0a

System Architecture
General

The entire system consists of two sides, both of which are extended by SimuCopter:
● PC/CONTROL STATION
Runs the MATLAB/Simulink software; allows design and live monitoring of flight modes; optional.
○ The Simulink software is expanded with ArduPilot-specific "SimuCopter Blocks". Said blocks
are used to access ArduPilot in various ways, whether to monitor its state, or even control it.
● RASPBERRY PI
A device/board that sits on top of the UAV; responsible for controlling it. This area has two subcomponents: the Simulink Agent and ArduPilot itself.
○ Simulink Agent is an executable compiled by the Simulink software and deployed onto the
Raspberry Pi (UAV). It runs on behalf of Simulink, keeps Simulink itself informed via the network, and executes commands on the device itself (including those that control ArduPilot).
■ Simulink Agent contains the Flight Mode Code that the user designed within it!
■ This component is expanded with RPC-like "bridge" client code that allows it to send
messages to ArduPilot, as well as receive information about the UAV's current state.
○ ArduPilot is the autopilot software with its basic capabilities.
■ This component is expanded with RPC-like "bridge" server code that handles
incoming requests/commands, and performs various procedures on demand.

SimuCopter Maintenance Manual
Version 1.0a

SimuCopter Integration Points

The SimuCopter system extends both sides with communication-related code:
● ARDUPILOT / SITL
Each of the two components is extended with a Bridge Service server-like module, whose purpose
is to receive requests and commands, handle/execute them, and respond as necessary:
○ The ARDUPILOT component interacts with the code in simucopter-arducopter.cpp
The initialization code is located in ardupilot/ArduCopter/system.cpp
○ The SITL component interacts with the code in simucopter-sitl.cpp
The initialization code is located in ardupilot/libraries/AP_HAL_SITL/HAL_SITL_Class.cpp
The code at these integration points enable communication with SIMULINK.
● SIMULINK
Extended with two Bridge Client modules, whose purpose are to send requests to the ARDUPILOT
and SITL component respectively, and receive responses from them.
The initialization code and the Simulink block functions are located in the provided
simucopter/simucopter-agent.cpp file and included from the simucopter.h header file (see one of
the Simulink block for an example)
Both of these sides share the same bridge library: a library that provides a transport of arbitrary messages
over ZeroMQ protocol. This bridge library is (and should be) identical on both sides, whereas the code that
uses it to send or process messages - is not.

SimuCopter Maintenance Manual
Version 1.0a

Communication

The communication between Simulink and ArduPilot is done using ZeroMQ socket pairs. There are two
types of pairs currently used in the bridge:
● REQ-REP (Request-Reply)
A "request" is delivered to the remote component. A "reply" must be provided by the remote
component before another request can be sent. This pair is used to pass REQUEST messages from
Simulink Agent to ArduPilot, and each request blocks execution until a response is received.
● PUB-SUB (Publish-Subscribe)
A publisher dispatches messages en masse to all its subscribers. A subscriber may not yet be
present, nor is it expected to keep up. If the subscriber cannot keep up, a message will be lost. This
pair is used to pass COMMAND messages from Simulink Agent to ArduPilot; I/O operations on
either side don't block execution.
Message Delivery Sequence
1. Simulink Agent executes simulink.h functions during its "step" function.

2. Each simulink.h function on the client side triggers an appropriate SimulinkBridgeInterface or
3.
4.
5.
6.
7.
8.
9.

SitlBridgeInterface method.
Each such method creates a REQUEST or COMMAND message (depending on the block).
Simulink/SitlBridgeIntergace passes the command to the BridgeClient for delivery.
BridgeClient sends the command through a ZeroMQ socket.
(REQ/REP for REQUEST messages, PUB/SUB for COMMAND messages)
BridgeService receives the command through a ZeroMQ socket belonging to the same socket pair.
BridgeSerivce passes the message to a RequestHandler or a CommandHandler.
Request/CommandHandler extracts data from the message, and executes relevant commands on
the ArduPilot or SITL side.
RequestHandler sends back a REPLY message with the resulting values (if applicable).

SimuCopter Maintenance Manual
Version 1.0a

Message Delivery Sequence (cont'd)
The following image illustrates the connection between each sub-component responsible for creating and
delivering messages:

Client-Side Delivery Sequence (REQUEST message example)

Server-Side Delivery Sequence (REQUEST message example)

This is a continuation of the sequence above as the server sees it:

SimuCopter Maintenance Manual
Version 1.0a

Caveats
Simulink shutdown quirks
● DO NOT run models with SITL blocks in "navio" mode!
If we are running in "navio" mode with SITL getter blocks, the Simulink diagram will lock up and will
be unable to shut down. This is because SITL BridgeService is down in "navio" mode - there is no
SITL running, and a request from it is expected indefinitely...
● DO NOT stop a model before aircraft is at rest!
Killing ArduPilot prematurely will keep the UAV in the state it was in when killed until ArduPilot is
restarted!
● The shutdown works. However, if the Simulink Agent is "stuck" before ArduPilot is fully operational
(T=0.000), or ArduPilot unexpectedly dies (i.e., "T=" value gets stuck), the shutdown will not work.
The agent has to be killed through the shell as root in such cases!
● Obviously, if the agent executable crashes of unexpectedly shuts down for any reason, the
ArduCopter process will also not be killed - you have to do this manually (see kill-arducopter.sh)!

Sporadic segmentation faults
WARNING: THIS PROBLEM IS STILL PRESENT!
At this point, ArduPilot appears to crash sporadically when using the SimuCopter infrastructure. The
backtrace of the crashes is as follows:
Program received signal SIGSEGV, Segmentation fault.
[Switching to Thread 0x759bf450 (LWP 5383)]
0x000bb6e8 in Linux::RCInput_RPI::_timer_tick() ()
(gdb) bt
#0 0x000bb6e8 in Linux::RCInput_RPI::_timer_tick() ()
#1 0x000be388 in Linux::PeriodicThread::_run() ()
#2 0x000be500 in Linux::Thread::_run_trampoline(void*) ()
#3 0x76d8be90 in start_thread (arg=0x759bf450) at pthread_create.c:311
#4 0x76d15598 in ?? () at ../ports/sysdeps/unix/sysv/linux/arm/nptl/../clone.S:92
from /lib/arm-linux-gnueabihf/libc.so.6
Backtrace stopped: previous frame identical to this frame (corrupt stack?)

The following is known about the crash:
● It does not seem to occur if all SimuCopter components are disabled.
● It never occurred in SITL mode.
● It does not occur immediately upon start.
If you get SEGV on start, you need to run as root - it's not the same case as this!
● The system is a lot more stable with the ASLR system DISABLED.
su -c "echo 0 | tee /proc/sys/kernel/randomize_va_space"

NOTE THAT THIS DOES NOT PREVENT CRASHES ALL TOGETHER - JUST REDUCES THE CHANCES!
● This ArduPilot bug report may be relevant: https://github.com/ArduPilot/ardupilot/issues/4850
It may be possible to upgrade ArduPilot to avoid these crashes all together… or not...
20

SimuCopter Maintenance Manual
Version 1.0a

Missing C++ library files in certain Simulink models
Currently, we are required to add all the ".cpp" files we use into the model configuration:
1. Tools → Run on Target Hardware → Options...
2. Select Code Generation / Custom Code
3. Check the Source Files section
There may be models on GitHub that are still missing the ArgumentPacker.cpp file in that list - that file is
relatively new! If your model does not compile due to ArgumentPacker-related issues, make sure that this
file was added to the model!
This is a Simulink quirk and we cannot help it...

define private public
Currently, there is no better way to extract information from ArduPilot than through "#define private
public". That said, this is the method used since before we took the project…

Message serialization - hardcoded buffers
The "message-to-bytes" serialization and deserialization code uses hardcoded 1024-byte buffers. This is no
big deal per se: the messages are MUCH smaller than that. However, those are hardcoded magic numbers
and likely need to be fixed in the long run (or changed to use a better method).
Search for "buffer[1024]" in the code - likely in the BridgeService.cpp or BridgeClient.cpp files.

No Simulink independence
While the model can be compiled and activated through MATLAB/Simulink, the agent itself may not yet be
standalone, and may not function without the Simulink software running! Such autonomous behavior was
not implemented during this year.

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.5
Linearized                      : Yes
Producer                        : Skia/PDF m61
Page Count                      : 21

EXIF Metadata provided by EXIF.tools

Maintenance Manual

Navigation menu

Versions of this User Manual:

Views

Navigation