Engee documentation

Software control of RITM

To work with the functions of the program control of the KPM "RITM" in Engee, install the Engee subsystem.Integrations:

engee.package.install("Engee-Device-Manager")

On this page all available functions of the program management of the KPM "RITM" in Engee are presented.

Methods RITM

Ritm(spec::AbstractString)::RITM.Ritm

Creates an object for controlling the RITM machine.

Arguments

  • spec::AbstractString: RITM machine specification. The machine specification can be defined in one of two ways:

    • the full URL, for example, "http://192.168.56.3:8000/";

    • the machine name or IP address stored in the machine’s memory (for example, "RITM 1" or "192.168.56.3"). The full URL is determined on the basis of the stored machine profile.

It is not possible to access a machine that has not been saved: it must first be added using the addMachine method or via the ‘RITM.Machine Management’ application; otherwise, the error '` ArgumentError ’ will occur.

Each call creates a new descriptor and replaces the cached machine descriptor. When string arguments are passed to the RITM_API methods, a shared descriptor is used for each machine, whilst an explicitly passed descriptor is used as is. If the client has been restarted, the descriptor will be automatically recreated on the next call with a string argument.

Examples

ritm = RITM_API.Ritm("http://192.168.56.3:8000/")
ritm = RITM_API.Ritm("192.168.56.3")
ritm = RITM_API.Ritm("RITM 1")
_resolve_ritm_address(spec::AbstractString)::String

Converts a machine specification into a full URL. If a full URL is passed, it is returned unchanged; otherwise, the machine is searched for in the repository by name or by its stored IP address. If the machine is not registered in the repository, a standard '` ArgumentError ’ exception is thrown, stating that the machine could not be found.

Arguments

spec::AbstractString: RITM machine specifications.

_ritm_cache_key(address::AbstractString)::String

The canonical registry key for the RITM machine address.

Arguments

  • address::AbstractString: hostname (in lower case) and port; if no port is specified, the default value RITM_MACHINE_DEFAULT_PORT is used. You may enter a full URL, the pair host:port or just the hostname; the components userinfo, IPv6 addresses in square brackets and query strings (query strings). Addresses without a specified scheme are interpreted as http://, to ensure that host:port pairs are not mistakenly taken for a scheme.

addMachine(name, ip; port="8000", is_default=false)::Nothing

Adds a RITM vehicle record to the vehicle database.

If the item is successfully added, a confirmation message is recorded in the log.

Throws a RitmMachinesStorageConflict exception if the store has been modified in the meantime: in this case, the list of machines should be re-read and the call repeated.

Arguments

  • name::AbstractString: machine name.

  • ip::AbstractString: The machine’s IP address.

  • port::AbstractString: the machine port. This argument is passed as a named argument (port="..."). The default value is "8000".

  • is_default::Bool: marks the machine as being used by default. This argument is passed as a named argument (is_default=true). The default value is false. If is_default=true, the new machine becomes the sole machine used by default.

Examples

RITM_API.addMachine("RITM 2", "192.168.56.4")
RITM_API.addMachine("RITM 3", "192.168.56.5"; is_default=true)
buildModel(ritm, model, is_interactive_mode::Bool=false)::Nothing

Collects and prepares the model for deployment on RITM.

Arguments

  • ritm::Any: a target platform for the RITM project.

  • model::Any: model structure.

  • is_interactive_mode::Bool: a flag indicating the model’s execution mode: true — the model is executed in interactive mode; false (by default) — the model is executed in standalone mode.

Examples

# We retrieve and run the model standalone — which is open in the canvas — on RITM:

model = engee.gcm()
RITM_API.buildModel(ritm, model, false)
RITM_API.runModel(ritm, model, false)
changeParam(ritm, block_key, param, data)::String

Changes a parameter of a model being executed on a RITM machine in interactive mode. The model’s execution is not interrupted; the new value is converted to the parameter type declared in the model on the host side.

The model must be built and run in interactive mode, i.e. with the parameter is_interactive_mode=true (for buildModel and runModel).

Returns a message indicating the result of the operation.

Arguments

  • ritm: address (URL), IP address or RITM hostname.

  • block_key::Union{String, UUID}: the path to the block within the model (e.g. "model_name/Block Name") or the block’s UUID.

  • param::String: parameter name.

  • data: new parameter value: a number, a Boolean value, or a vector of numbers or Boolean values.

Examples

RITM_API.changeParam(ritm, "my_model/Gain", "Gain", 2.5)
disableAutostart(ritm)::Dict{String, Union{String, Int64, Bool, Nothing}}

Removes the model from the startup list.

Arguments

  • ritm::Any: a target platform of the RITM programme.

Examples

RITM_API.disableAutostart(ritm)
downloadFile(ritm, filename; from="/home/ritm/", to=pwd())::Nothing

Downloads a file from the RITM machine to the Engee local directory.

Arguments

  • ritm::Any: a target platform for the RITM project.

  • filename::AbstractString: the name of the file to be uploaded.

  • from::AbstractString: the source directory on the RITM machine. This argument is passed as a named argument (from="..."). The default value is "/home/ritm/".

  • to::AbstractString: local destination directory. This argument is passed as a named argument (to="..."). The default value is the current directory.

Examples

RITM_API.downloadFile(ritm, "profile.txt"; from="/home/ritm/build/my_model/", to="/tmp/")
getAutostart(ritm)::Union{Dict{String, Union{String, Int64, Bool, Nothing}}, Nothing}

Retrieves the model that is set to start automatically.

Arguments

  • ritm::Any: a target platform for the RITM programme.

Examples

RITM_API.getAutostart(ritm)
getData(ritm::Any, model_name::String, file_path::String, in_file::Bool = false)

Returns the result of profiling the model on RITM. Depending on the value of in_file, the result may be returned as a string or saved to a file at the specified path.

Arguments

  • ritm::Any: a target platform for the RITM project.

  • model_name::String: the name of the model for which the profiling data is being requested.

  • file_path::String: the path to which the result should be saved (if in_file = true). If in_file = false, the value is ignored.

  • in_file::Bool = false: specifies how the result is to be returned. If true, the data is saved to a file using file_path. If false, a string containing the result is returned.

Examples

# Retrieve profiling data as a string
result = RITM_API.getData(ritm, "newmodel_1", "", false)

# Save the data to a file on RITM
RITM_API.getData(ritm, "newmodel_1", "/user/profile.txt", true)
getDiagnostic(ritm)::Nothing

Downloads the diagnostic archive ritm_diagnostic.zip to the current Engee directory.

Arguments

  • ritm::Any: a target platform for the RITM project.

Examples

RITM_API.getDiagnostic(ritm)
getFile(ritm::Any, file_name::String; from::String, to::String)

Retrieves the specified file file_name from the directory from.

Arguments

  • ritm::Any: a target platform for the RITM project.

  • file_name::String: the name of the file in question.

  • from::String: the path to the relevant directory (by default, /home/ritm/).

  • to::String: the path to the directory in Engee where the file is to be saved (by default, the current directory).

Examples

# Download the file install_manifest.txt from the directory /home/ritm/build/newmodel_1/build to the current directory Engee:

RITM_API.getFile(ritm, "install_manifest.txt"; from="/home/ritm/build/newmodel_1/build/", to="")
getIPByName(name::AbstractString)::Union{String, Nothing}

Returns the IP address of the RITM machine stored in the machine repository.

Arguments

  • name::AbstractString: the machine name stored in the machine store.

Examples

RITM_API.getIPByName("RITM 1")
getLog(ritm, number_of_lines::Int64)::String

Returns the specified number of model execution log entries on RITM.

Arguments

  • ritm::Any: a target platform for the RITM project.

  • number_of_lines::Int64: the number of lines to be output from the logs.

Examples

RITM_API.getLog(ritm, 10)
getMachines()::Vector{Dict{String, Any}}

Returns a vector of descriptions for the RITM machines stored in the machine repository.

Each description consists of a dictionary with the following keys: "name", "ip", "port" and "default".

Examples

RITM_API.getMachines()
getNameByIP(ip::AbstractString)::Vector{String}

Returns the names of all RITM machines with the specified IP address.

The result is always a vector: one name for each corresponding machine, several names where IP addresses are duplicated (in the order in which they are stored), or an empty vector if there is no machine with that IP address.

Arguments

  • ip::AbstractString: The machine’s IP address.

Examples

RITM_API.getNameByIP("192.168.56.3")
getProfileData(ritm, model_name; engee_location="/user/", in_file=false)::Union{String, Nothing}

Retrieves model profiling data collected on the RITM machine.

If in_file=false, it returns the data as a string. If in_file=true, it writes the data to the file <model_name>.txt in the specified local directory and returns nothing.

Arguments

  • ritm::Any: a target platform for the RITM project.

  • model_name::AbstractString: model name.

  • engee_location::AbstractString: the local directory in which to save the file if in_file=true. This argument is passed as a named parameter (engee_location="..."). The default value is /user/.

  • in_file::Bool: data retrieval mode. If set to false , a string is returned; if set to true , the data is written to a file and no value is returned. This argument is passed as a named parameter (in_file=true).

Examples

data = RITM_API.getProfileData(ritm, "my_model")
RITM_API.getProfileData(ritm, "my_model"; engee_location="/user/", in_file=true)
getPtpSettings(ritm)::Vector{String}

Retrieves the saved PTP settings. Returns the PTP settings — a row vector containing the selected interface, delay mechanism, network transport, role and PTP clock attributes.

Arguments

  • ritm::Any: a target platform for the RITM project.

Examples

RITM_API.getPtpSettings(ritm)
getPtpState(ritm)::Vector{String}

Retrieves the PTP state. Returns the current PTP state: running or stopped, as well as the interface and role, if PTP is running.

Arguments

  • ritm::Any: a target platform for the RITM project.

Examples

RITM_API.getPtpState(ritm)
getScreenshot(ritm, filename::String="screenshot.png"; to=pwd())::String

Takes a screenshot on the target RITM platform and uploads it to the Engee file system.

Arguments

  • ritm::Any: a target platform for the RITM project.

  • filename::String = "screenshot.png": the name of the file in which the screenshot will be saved (on the RITM side).

  • to=pwd(): the local target directory on the Engee side. This argument is passed as the named parameter (to="..."). The default value is the current directory.

Examples

# Takes a screenshot and retrieves the path to it
path = RITM_API.getScreenshot(ritm, "example.png")
isConnected(ritm::Any)::Bool

Checks whether the RITM machine is available. Returns true if the RITM machine is available, and false otherwise.

Arguments

  • ritm::Any: a target platform for the RITM project.

Examples

RITM_API.isConnected(ritm)
isMachineExists(name::AbstractString)::Bool

Checks whether the RITM machine with the specified name has been saved in the machine repository.

Returns true if the car exists, and false otherwise.

Arguments

  • name::AbstractString: machine name.

Examples

RITM_API.isMachineExists("RITM 1")
isRunning(ritm::Any, model_name::String)::Bool

Checks whether the specified model is running on the target RITM platform. Returns true if the model with the specified name is currently running on the RITM machine, and false if it is not running.

Arguments

  • ritm::Any: a target platform for the RITM project.

  • model_name::String: the name of the model whose state needs to be checked.

Examples

# Checks whether the model "newmodel_1" is running
is_active = RITM_API.isRunning(ritm, "newmodel_1")
listFiles(ritm, path::String)::Vector{String}

Returns a list of files in the specified directory.

Arguments

  • ritm::Any: a target platform for the RITM project.

  • path::String: the path to the directory of interest.

Examples

RITM_API.listFiles(ritm, "/home/ritm/")
memInfo(ritm, model_name=nothing)::Union{Vector{Int64}, Int64}

Returns a vector of values containing information about system memory, or a single integer representing the amount of memory used by a specific model.

Arguments

  • ritm::Any: a target platform for the RITM project.

  • model_name::Union{String, Nothing}: model name. If this argument is omitted or set to an empty string, information about system memory is returned. If a model name is specified, the amount of memory consumed by the model

Examples

RITM_API.memInfo(ritm, "newmodel_1")
poweroff(ritm)::Dict{String, Union{String, Int64, Bool, Nothing}}

Switches the machine off.

Arguments

  • ritm::Any: a target platform for the RITM project.

Examples

RITM_API.poweroff(ritm)
readFile(ritm, filename::String; path="/home/ritm/")::String

Returns the contents of the specified file on the RITM machine.

Arguments

  • ritm::Any : the RITM target platform object.

  • file_name::String : the name of the file in question.

  • path::String : the path to the directory on the RITM machine. This argument is passed

as a named argument (path="..."). The default value is "/home/ritm/".

Examples

# Displays the contents of the file install_manifest.txt from the directory /home/ritm/build/newmodel_1/build:

RITM_API.readFile(ritm, "install_manifest.txt"; path="/home/ritm/build/newmodel_1/build/")
reboot(ritm)::Dict{String, Union{String, Int64, Bool, Nothing}}

Reboots the machine.

Arguments

  • ritm::Any : an object representing the target RITM platform.

Examples

RITM_API.reboot(ritm)
removeFile(ritm::Any, path::String)::String

Deletes a file at the specified path on the target RITM platform. Returns a message indicating the status of the file deletion.

Arguments

  • ritm::Any : an object representing the target RITM platform.

  • path::String : the path to the file to be deleted from RITM.

Examples

# Deletes the file newmodel_1 on RITM:
RITM_API.removeFile(ritm, "/home/ritm/newmodel_1.engee")
removeMachine(name::AbstractString)::Nothing

Deletes a RITM machine card from the machine repository.

Throws a '` RitmMachinesStorageConflict ’ exception if the repository has been modified in the meantime: re-read the list of machines and repeat the call.

If the deletion is successful, a confirmation message is logged.

Arguments

  • name::AbstractString : machine name.

Examples

RITM_API.removeMachine("RITM 2")
resetPtpSettings(ritm)::Dict{String, Union{String, Int64, Bool, Nothing}}

Resets the saved PTP settings on the RITM. Returns a dictionary with the result of the operation: status and error message (if any).

After resetting, reconfigure the interface via setupEthPtp before starting PTP.

Arguments

  • ritm::Any : the target RITM platform object.

runModel(
    ritm,
    model,
    is_interactive_mode::Bool=false;
    simulation_uuid=string(uuid4()),
    status_callback=nothing,
    termination_callback=nothing,
)::Union{Channel{TargetSimulationStatus}, Nothing}

Runs a previously built model on RITM.

In standalone mode, returns nothing. In interactive mode, returns the channel through which updates are transmitted of the status of the model’s execution.

Arguments

  • ritm::Any : the RITM target platform object.

  • model::Any : the model structure.

  • is_interactive_mode::Bool : a flag specifying the model execution mode: true — the model is executed in interactive mode; false (default) — the model is executed in standalone mode.

  • simulation_uuid::String : launch identifier for interactive mode.

  • status_callback : this function is called for each execution status received.

  • termination_callback : this function is called upon completion of interactive execution.

Examples

RITM_API.runModel(ritm, model)
setAutostart(ritm, model_name::String)::Dict{String, Union{String, Int64, Bool, Nothing}}

Puts the model into autostart mode.

Arguments

  • ritm::Any : the RITM target platform object.

  • model_name::String : the model name.

Examples

RITM_API.setAutostart(ritm, "my_model")

setupEthPtp(
    ritm,
    eth_number,
    role;
    delay_mech="E2E",
    network_tr="UDPv4",
    priority1=128,
    priority2=128,
    clock_class=248,
    clock_accuracy=254,
)::Dict{String, String}

Configures PTP on the selected RITM Ethernet interface. Returns a dictionary containing the result of the operation: status and error message (if any).

Arguments

  • ritm::Any : the target RITM platform object.

  • eth_number : the RITM Ethernet interface number; for example, 1 for Ethernet 1.

  • role : specifies the role of the local PTP clock: "Master" or "Slave".

  • delay_mech : PTP operating mode. Possible values "E2E", "P2P" or "Auto". Default value "E2E".

  • network_tr : network protocol. Possible values "UDPv4", "UDPv6" and "L2". Default value "UDPv4".

  • priority1 : local clock attribute "Priority 1". Possible range from 0 to 255. Default value 128.

  • priority2 : local clock attribute "Priority 2". Valid range: from 0 to 255. Default value: 128.

  • clock_class : local clock attribute "Class". Valid range: from 0 to 255. Default value: 248.

  • clock_accuracy : local clock attribute "Accuracy". Valid range: from 0 to 255. Default value: 254.

setupEthernet(ritm, interface_id::Int64, ip::String, mask::Int64)::Dict{String, Union{String, Int64, Bool, Nothing}}

Configures the machine’s Ethernet interface.

Arguments

  • ritm::Any : RITM target platform object.

  • interface_id::Int64 : Ethernet interface identifier.

  • ip::String : IP address of the interface.

  • mask::Int64 : subnet mask.

Examples

RITM_API.setupEthernet(ritm, 0, "192.168.0.10", 24)
startPtp(ritm, eth_number)::Dict{String, Union{String, Int64, Bool, Nothing}}

Starts PTP on the selected RITM Ethernet interface. Returns a dictionary containing the result of the operation: status and error message (if any).

Before starting PTP, you must configure the interface via setupEthPtp.

Arguments

  • eth_number : the Ethernet interface number. Possible values are "HostTarget" or "1" — "max ethernet number".

Examples

RITM_API.startPtp(ritm, 1)
stopModel(ritm)::Nothing

Stops the model on RITM.

Arguments

  • ritm::Any : the target RITM platform object.

Examples

RITM_API.stopModel(ritm)
stopPtp(ritm, eth_number)::Dict{String, Union{String, Int64, Bool, Nothing}}

Stops PTP on the selected RITM Ethernet interface. Returns a dictionary containing the result of the operation: status and error message (if any).

Arguments

  • eth_number : Ethernet interface number. Possible values "HostTarget", "1" or "max ethernet number".

Examples

RITM_API.stopPtp(ritm, 1)

updateFirmware(
    ritm,
    firmware_path::String="",
    checksum_path::String="";
    reboot::Bool=true,
    show_progress=false,
)::Nothing

Updates the RITM firmware.

Arguments

  • ritm::Any : the target RITM platform object.

  • firmware_path::String : the local path to the firmware file.

  • checksum_path::String : the local path to the checksum file.

  • reboot::Bool : Restarts the RITM machine after a successful update. Default value — true.

  • show_progress::Bool : Logs information about the progress of the update. Default value — false

Examples

RITM_API.updateFirmware(ritm; show_progress=true)
RITM_API.updateFirmware(ritm, "/user/firmware.raucb", "/user/firmware.raucb.checksum")
updateSupportPackage(ritm, support_package_path::String=""; show_progress=false)::Nothing

Updates the RITM support package.

If the argument support_package_path is not specified, the package corresponding to the current version of Engee is installed. If the argument support_package_path is specified, the package from the specified local file is installed.

Arguments

  • ritm::Any : the target RITM platform object.

  • support_package_path::String : the local path to the support package.

  • show_progress::Bool : log information about the progress of the update.

Examples

RITM_API.updateSupportPackage(ritm)
RITM_API.updateSupportPackage(ritm, "/user/ritm_support_package.tar.gz"; show_progress=true)
uploadFile(ritm::Any, filename::AbstractString; from::AbstractString=pwd(), to::AbstractString="/home/ritm")::String

Downloads a file from Engee to the target RITM platform.

Arguments

  • ritm::Any : the target RITM platform object.

  • filename::AbstractString : the name of the file to be downloaded to RITM.

  • from::AbstractString = pwd() : the path in Engee to the directory where the file to be uploaded is located (by default — the current directory).

  • to::AbstractString = "/home/ritm" : the path on RITM where the file will be uploaded (by default — /home/ritm).

Examples

using EngeeDeviceManager.Targets
using EngeeDeviceManager.Targets.RITM_API

# Creates a RITM machine object and sets the address
ritm = Targets.RITM_API.Ritm("http://192.168.56.3:8000/")

# Downloads the file test.bin from the current directory Engee (pwd()) to /home/ritm on RITM
res = RITM_API.uploadFile(ritm, "test.bin")

# Downloads a file from the specified directory Engee (/user/...) to the specified directory on RITM
res = RITM_API.uploadFile(ritm, "install_manifest.txt"; from="/user/project/", to="/home/ritm/data/")
version(ritm)::Dict{String, String}

RITM firmware and support package versions. Returns a dictionary with the following keys:

  • "firmware" — firmware version.

  • "support_package" — support package version (sysimage).

Arguments

  • ritm::Any : the RITM target platform object.

Examples

RITM_API.version(ritm)

  1. RITM

  2. Model execution modes

  3. RITM.Manager