Table of Contents
Multiwii Connect
Connects to an auto-pilot. This block is intended for use in the main diagram.
Library
MATLAB Command Line
Click to copy the following command line to the clipboard. Then paste it in the MATLAB Command Window:
qc_open_library('quarc_library/Communications/Multiwii')Description
The Multiwii Connect block establishes a connection to an auto-pilot using blocking I/O. Blocking I/O is used because auto-pilots are typically interfaced using a serial port and the Multiwii protocol requires acknowledgements. Note, however, that all the I/O should be completed within one sample time or the model will fall behind real-time.
The first time the block executes it begins to connect to the auto-pilot using the given URI. It does not wait for the connection to be established, but continues the connection process each time the block executes. Once a connection is established, it outputs the connection at its stm port. This stream signal is passed as an input to other Multiwii blocks to refer to the stream.
The connection is maintained as long as the cls input remains zero or false
. If the cls input becomes
non-zero then it closes the connection. When the cls input returns to zero then it reestablishes a connection as it
did in the beginning. Note that the connection will not be established the first time the block executes if the cls
input is non-zero at that time. When the block is not connected to an auto-pilot then it outputs an invalid stream at its
stm port so the other Multiwii blocks know not to use the connection.
The current state of the connection is output at the con port. The states and their integral values are:
Connection State |
Value |
Description |
---|---|---|
STREAM_CALL_STATE_NOT_CONNECTED |
0 |
The stream is not connected. |
STREAM_CALL_STATE_CONNECTING |
1 |
The stream is in the process of being connected to the remote host but is not yet ready for communications. |
STREAM_CALL_STATE_CONNECTED |
2 |
The stream is fully connected and communication may occur over the stream. |
If an error occurs then the err output will be a negative error code. Otherwise the err output will be zero. Note that only errors that occur in establishing the connection are reported. Once the connection is established this block simply outputs the stream. It does not detect if the connection is lost due to an error. As a result, it will not close the connection if the auto-pilot closes the connection or an established connection is lost. Instead, the other Multiwii blocks will report an error if the connection is lost and when they do, the cls input of the Multiwii Connect block should be set to a non-zero value to close the current connection. Typically, a Compare To Zero block is used with the other Multiwii blocks to detect if an error occurs (if the err output of these blocks is less than zero) and the output of the Compare To Zero block is fed to the cls input of the Multiwii Connect block. Doing so ensures that the connection is closed when an error occurs and that the connection is reestablished as soon as possible.
The connection is closed when the model is terminated or the cls input is non-zero. Note that the cls input must be maintained at a non-zero value to ensure that the connection remains closed. Otherwise the Multiwii Connect block will reconnect.
Auto-pilots are identified by a Universal Resource Identifier (URI), such as serial://localhost:1?baud=115200. QUARC uses URI's for all its communications because it provides a uniform, extensible and flexible means of identifying the communication protocol to use and the associated communication parameters. Refer to Universal Resource Identifiers for more information.
The URI may be specified in the dialog parameters or via an input port. Which option is used is determined by the Source of URI parameter. When the URI is specified via an input, the input is typically driven by a Model Argument block, which allows a model argument to be used to assign the URI at runtime.
When the URI is specified as a dialog parameter and is not evaluated then the URI is configuration-dependent. A separate URI may be entered for each model configuration as well as for normal simulation. Thus, it is possible to employ a different URI for each target, without making a new diagram. The URI that is entered becomes the URI for the currently active configuration when the Simulation mode is set to
. It becomes the URI for normal simulation when the Simulation mode is set to .Streams have an associated buffer that is independent of any buffering in the underlying protocol. The stream buffer is designed to maximize use of the available bandwidth. The buffer sizes must be large enough to support the Multiwii Serial Protocol (MSP) packets being used by the Multiwii blocks.
The Multiwii Connect block sends a command to the auto-pilot to set the final outputs of the actuators at model termination to ensure that the motors stop spinning. The final output values may be configured using the Final outputs parameter.
If this parameter is an empty matrix, then the final outputs are not set and the behaviour is determined by the auto-pilot. For example, the auto-pilot may lower the throttle after one second because RC commands are no longer being sent after the model stops (assuming the MSP protocol was being used to send RC commands). In that case, it may be necessary to rerun the model and explicitly zero the outputs to stop the motors.
Limitations
Flight Controller
Flight controllers typically handle Multiwii serial packets in a periodic task that only processes one packet each time the task runs. When multiple Multiwii blocks are used, this periodicity slows down communications because this task only replies to one block each time the task runs (each Multiwii block represents a single packet). The default rate of this task is 100 Hz. However, it may be possible to increase this rate by setting a variable in the command-line interface (CLI) of the flight controller, such as serial_update_rate_hz. A typical flight controller supports rates up to 2000 Hz. Increasing the rate will increase the frequency at which Multwii blocks are processed by the flight controller.
Input Ports
cls
Used to close the stream. Setting this input to a non-zero value will cause the connection to be closed. The connection will remain closed as long as this input is non-zero. When this input is zero or false, then a new connection will be established. The connection will be maintained as long as this input is zero.
uri
A string specifying the URI to which to connect. The string must be a null-terminated vector of characters represented
as a vector of uint8
quantities. It may be variable-sized. This string is typically provided
either directly or indirectly by a Model Argument
block or String Constant block.
This input is only available if the Source of URI parameter is
set to External input port
. Refer to the documentation below on the
Source of URI parameter for details.
Output Ports
stm
A reference to the stream. This reference is always valid but will not refer to a connected stream if the connection was not established or is still pending. It has a data type of t_stream_ptr. It cannot be plotted and may only be connected to the stm input of one of the Multiwii blocks.
con
A uint8 state code indicating the current status of the connection. The different connection states and their values are given in the table above in the Description section.
err
An int32 error code indicating the results of the operation. If there are no errors during the establishment of a connection, then this output will be zero. Otherwise a negative error code is returned. See Error Codes for the different error codes and their values. Use the Compare to Error block rather than the error code itself to check for specific error codes.
Parameters and Dialog Box
Source of URI
Indicates whether the URI should be determined from the dialog parameters or an
input port. If this field is set to Specify via dialog (do not evaluate)
then
the URI is specified via the URI of host to which to connect
parameter. In this case, the URI is not evaluated as a MATLAB expression but is
interpreted as a literal string. However, format specifiers are recognized. Refer
to qc_perform_substitutions
for a list of the format specifiers available.
If format specifiers which change frequently, such as '%{time}' or
'%{instance}', are used in the URI then the Multiwii Connect block cannot be placed
in a referenced model, because the URI will change from the time the code is built to when
the code is run. As a result, Simulink will insist that the code be rebuilt because block
parameters in referenced models are inlined. Instead, specify the source of the URI as
External input port
and pass the URI from the top-level model. Use a
String Constant block
in the top-level model to generate the URI.
If this field is set to Specify via dialog (evaluate)
then the URI is also specified
via the URI of host to which to connect parameter. However, in this case,
the URI is evaluated as a MATLAB expression. This option is convenient for using a variable
in the MATLAB workspace for the URI.
If this field is set to External input port
then the URI of host to which to connect
parameter is ignored and an extra input port is provided which determines the URI.
URI of host to which to connect (tunable offline)
The URI identifying the auto-pilot to which to connect. This parameter identifies the communication protocol
and associated parameters. For example, serial://localhost:1?baud=115200
connects to through serial port 1 (e.g. COM1 or /dev/ttyS1) at 115200 baud. This
field is only used if the Source of URI parameter
is set to Specify via dialog (do not evaluate)
or Specify via dialog (evaluate)
.
Refer to Universal Resource Identifiers
for more information about URIs and the communications protocols supported by QUARC.
Send buffer size in bytes (tunable offline)
The size of the buffer used by the stream for sending data. This buffer is independent of any buffering in the underlying communication protocol. Increasing the buffer size may increase transmission performance. The buffer size must be at least as large as the maximum packet size that will be sent in bytes.
Receive buffer size in bytes (tunable offline)
The size of the buffer used by the stream for receiving data. This buffer is independent of any buffering in the underlying communication protocol. Increasing the buffer size may increase reception performance. The buffer size must be at least as large as the maximum packet that will be received in bytes.
Byte ordering (tunable offline)
The order in which bytes are transmitted or received. Little endian ordering means that the least significant byte of individual values, such as doubles, is transmitted or received first. Big endian ordering means that the most significant byte of individual values is transmitted or received first. The auto-pilot must use the same byte ordering.
Final output units (tunable offline)
The units to use for the Final outputs parameter. The table below shows the input for each of the different units:
Units |
Data Type |
Description |
---|---|---|
Bipolar percentage |
double |
Each element maps the input range of [-1,1] to the typical [1000,2000] range such that -1 becomes 1000, 0 becomes 1500 and 1 becomes 2000. Any values outside this range are mapped according to the same affine transformation. These units are useful when the RC data represent -100% to 100% throttle. |
Unipolar percentage |
double |
Each element maps the input range of [0,1] to the typical [1000,2000] range such that 0 becomes 1000 and 1 becomes 2000. Any values outside this range are mapped according to the same affine transformation. These units are useful when the RC data represent 0 to 100% throttle. |
Seconds |
double |
Each element maps the input range of [0.001,0.002] to the typical [1000,2000] range such that 0.001 becomes 1000 and 0.002 becomes 2000 so that the input is the RC pulse width in seconds. Any values outside this range are mapped according to the same affine transformation. These units are useful when the RC data are being used to drive PWM pulse widths via the HIL blocks. |
Microseconds (raw) |
uint16 |
Each element is the raw RC value, which is the RC pulse width in microseconds. |
Final outputs (tunable online)
The final output values to write to the motors when the model is stopped. The Multiwii Connect block ensures that these values are written to the actuators on model termination so that the motors do not continue spinning. If this parameter is an empty matrix then no final outputs are written.
Sample time
The sample time of the block. A sample time of 0 indicates that the block will be treated as a continuous time block. A positive sample time indicates that the block is a discrete time block with the given sample time.
A sample time of -1 indicates that the block inherits its sample time. Since this is a source block, only inherent the sample time when it is placed in a conditionally executed subsystem, like a Triggered Subsystem, Enabled Subsystem, Function Call Subsystem or in a referenced model.
To use the fundamental sampling time of the model, set the sample time to qc_get_step_size, which is a QUARC function that returns the fundamental sampling time of the model.
The default sample time is set to qc_get_step_size.
Active during normal simulation (tunable offline)
Indicates whether this block should execute during normal simulation. If this option is not checked then the block will not connect to the remote host during normal simulation. This parameter has no effect on generated code.
Targets
Target Name |
Compatible* |
Model Referencing |
Comments |
---|---|---|---|
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
||
Yes |
Yes |
Last fully supported in QUARC 2018. |
|
Rapid Simulation (RSIM) Target |
Yes |
Yes |
|
S-Function Target |
No |
N/A |
Old technology. Use model referencing instead. |
Normal simulation |
Yes |
Yes |
See Also
Copyright ©2024 Quanser Inc. This page was generated 2024-10-17. Submit feedback to Quanser about this page.
Link to this page.