Engee documentation

Software control of RITM

To work with the functions of the KPM software management «RITM» in Engee. install the hardware support package as specified in article. After installation, import the module and add the RITM machine:

using Main.EngeeDeviceManager.Targets: RITM_API

if !RITM_API.isMachineExists("RITM 1")
    RITM_API.addMachine("RITM 1", "192.168.56.3")
end

Replace the name and IP address in the example with the values of your RITM machine, or use an already registered machine.

This page presents all the available functions of the KPM software management «RITM» in Engee.

Methods RITM_API

For most functions, the first argument is name::String — the name or IP address of the machine stored in Engee (for example "RITM 1", "192.168.56.3"). The machine must be pre-added via RITM_API.addMachine or in the app RITM.Manager ritm icon. If the machine is turned off or the client program Engee.Integration not connected to Engee, the call returns an error with a description of the reason or an exception.

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)
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)
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)
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