Host Initialize

Initializes host devices for use with local or remote targets.

Library

Description

QUARC supports the use of the mouse and keyboard on the host, along with other peripherals, to be used by models running on local or remote targets. For example, a mouse or game controller on the host PC can be used to control a mobile robot driven by an embedded gumstix module running QUARC. While this feature has existed for a while, QUARC 2.2 introduced a whole new framework for handling host devices that provides more flexibility and higher performance.

The Host Initialize block is a key component in this new framework. With the greater flexibility offered by the new host framework, a new block was required to configure the host device support. The Host Initialize block provides a centralized location for configuring this support.

In terms of features, the new host framework adds two exciting capabilities to QUARC: the ability to use host devices with remote targets even without Simulink running on the host, and the option of restricting the use of host devices to a single window on the host rather than the entire desktop.

To support the use of host peripherals without Simulink running, QUARC provides a Host Peripheral Client application that monitors host devices and communicates with the Host Initialize block running on a QUARC target. This application can be run manually via its menu item under the Start/Quanser/QUARC menu, or automatically when interfacing to the model through Simulink.

The protocol used to communicate between the Host Peripheral Client application and the model running on the target is identified by a Universal Resource Identifier (URI), such as tcpip://remotehost:8000 or shmem://mymemory:1?local=no. 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 Source of URI parameter determines how the host framework actually communicates information about host peripherals to the model running on the target. The default option is Use external mode communications, which uses the external mode connection between Simulink and the model to communicate information about the host peripherals. This option is the simplest to use but requires that Simulink be running for the host peripherals to be recognized by the model.

The other three options for the source URI all result in the Host Peripheral Client application being used to communicate host peripheral information to the model on the target. The only difference is how the URI is specified - be it a fixed string, an evaluated expression or an external input port to the Host Initialize block. With these options, Simulink is not actually required to use the host peripherals. Instead, the Host Peripheral Client application must be run and connected to the model. The Host Peripheral Client application presents an icon in the system tray. Right-clicking on this tray icon opens a menu that can be used to connect to the model. Refer to Host Peripheral Client for more information.

If the Run Host Peripheral Client at model start option is checked and Simulink is used to connect to the model, then the Host Peripheral Client application is run automatically at model start and passed the correct URI so that no manual intervention is required.

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.

No matter which URI source is selected, input from host peripherals can be restricted to a window instead of the entire desktop. Checking the Use a window instead of entire desktop option causes a special "peripheral client window" to be opened when the model is started (or the Host Peripheral Client application is started). This window is shown below.

Host peripherals will only be recognized when this window is the active window. Otherwise they are ignored. This feature can be useful for taking advantage of the mouse as a host device, for example, because it allows button clicks and mouse movement outside the peripheral client window to be treated normally and be ignored by the model. The peripheral client window also provides other features, such as grid lines and message logging. Refer to the documentation on the Host Peripheral Client application for details.

The current state of the connection between the Host Initialize block and the client running on the host is output at the state port. The states and their integral values are:

If an error occurs then the err output will be a negative error code. Otherwise the err output will be zero.

Limitations

External Mode Communications

Only one Host Initialize block in a model may use external mode communications.

Input Ports

uri

A string specifying the URI upon which to listen and service client connections. 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

state

A uint8 state code indicating the current status of the connection between the Host Initialize block and the client running on the host. The different connection states and their values are given in the table above in the Description section.

err

An int32 error code indicating any errors that have occurred. If there are no errors, then this output will be zero. 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

Goto Host blocks using this host interface

Opens a dialog that lists all the Host blocks in the model which are currently using the same host selected in the Host name parameter. The dialog may be used to go to another Host block in the model just by double-clicking on the name of the block in the dialog box.

Host name

A name used to identify this host connection. This name is used by other Host blocks to refer to this connection.

Source of URI

This parameter determines whether the external mode connection between Simulink and the model is used to transmit host peripheral information to the model, or whether the Host Peripheral Client application should be used to communicate the information.

When the Source of URI option is set to Use external mode communications then the external mode connection between Simulink and the model is used. This option is the easiest one to use, but requires that Simulink be connected to the model for the host peripherals to be recognized. No other configuration is required in this case.

If this parameter is set to any of the other options then the Host Peripheral Client application is used to communicate with the model, instead of Simulink. Hence, Simulink does not have to be connected or even running for the host peripherals to be used with the model running on the target. Communications between the Host Peripheral Client application and the model is governed by the URI, like all communications in QUARC.

If the Source of URI parameter is set to Specify via dialog (do not evaluate) then the URI is specified via the URI upon which to listen 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 Host Initialize 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 upon which to listen 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 upon which to listen parameter is ignored and an extra input port is provided which determines the URI.

URI upon which to listen (tunable offline)

Identifies the URI upon which to listen. This parameter identifies the communication protocol and associated parameters. For example, a URI of tcpip://quanser-dev:18000 will cause the Host Initialize block to use TCP/IP and listen for connections on port 18000. 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.

If the model is being run on a remote target, then the hostname portion of this URI should be the hostname of the remote target, not the host machine running MATLAB. For example, if the remote target is called quanser-dev then tcpip://quanser-dev:18000 would be a suitable URI.

Send buffer size in bytes (tunable offline)

The size of the buffer used for the stream for sending data. This buffer is independent of any buffering in the underlying communication protocol. The buffer size must be at least as large as the maximum number of bytes that will be sent at any given time, which is determined by the other Host blocks in the model.

Receive buffer size in bytes (tunable offline)

The size of the buffer used for the stream for receiving data. This buffer is independent of any buffering in the underlying communication protocol. The buffer size must be at least as large as the maximum number of bytes that will be received at any given time. which is determined by the other Host blocks in the model.

Priority of communications (tunable offline)

The priority of the thread used in the model to communicate with the Host Peripheral Client application running on the host. This parameter is ignored if external mode communications is used. In general, a value of 0 indicates the lowest priority and higher values indicate a higher priority. The number of priority levels available depends on the type of QUARC target for which code is being generated.

Run Host Peripheral Client at model start (tunable offline)

If this option is checked, then connecting to the model in Simulink causes it to run the Host Peripheral Client application automatically, with the correct URI. The Host Peripheral Client application will connect to the model and remain running until the Simulink diagram is disconnected from the model. This option makes the operation of the Host Peripheral Client application transparent as long as Simulink is being used to connect to the model.

The URI upon which to listen parameter contains the URI that will be used by the Host Peripheral Client. Hence, if the model is being run on a remote target, then the hostname portion of this URI should be the hostname of the remote target, not the host machine. For example, if the remote target is called mytarget then the URI may be tcpip://mytarget:18001.

Use a window instead of the entire desktop (tunable offline)

Checking this option causes a special "peripheral client window" to be opened when connecting to the model. Host peripherals are ignored unless this window is the active window.

Window position (tunable offline)

When the Use a window instead of the entire desktop option is checked the position and size of the peripheral client window that is opened may be specified using this parameter. Enter the left, top, right and bottom coordinates of the window in pixels as a four-vector. To use the default position simply enter an empty matrix, []. By default, the most recent position of the window is used.

Sample time

The sampling period (in seconds) of the Host Initialize 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 or Enabled Subsystem, or in a referenced model.

The default sample time is set to qc_get_step_size, which is a QUARC function that returns the fundamental sampling time of the model. Hence, the default sample time is a discrete sample time with the same sampling time as the fixed step size of the model.

Active during normal simulation (tunable offline)

Indicates whether this block should communicate during normal simulation. Other Host blocks in the model that are associated with this connection will not do anything in normal simulation unless this option is checked.

Targets

See Also

• Devices on the Host PC

Copyright ©2024 Quanser Inc. This page was generated 2024-10-17. Submit feedback to Quanser about this page.

Link to this page.