Engee documentation

Programmatic target management

This page presents the functions of programmatic target management in Engee.

To work with the target management software functions in Engee. install the hardware support package as specified in article. After that, perform:

using Main.EngeeDeviceManager.Targets

Description of functions

build_deploy_start(
    target::Target,
    model;
    is_external_mode::Bool=false,
    simulation_uuid::String=string(uuid4()),
    status_callback::Function=((args...) -> nothing),
    termination_callback::Function=((args...) -> nothing),
)::Union{Channel{TargetSimulationStatus},Nothing}

A function designed to generate the model code, build it, upload it to the target, and run the model on the target.

Arguments

  • target::Target: target instance.

  • model: model Engee.

  • is_external_mode::Bool=false: Launch mode.

  • simulation_uuid::String: The UUID of the simulation.

  • status_callback::Function: A function that is called when a simulation status message is received.

  • termination_callback::Function: completion callback.

compile_model(target::Target, model)::TargetResponse

A function designed to build a model.

Arguments

  • target::Target: target instance.

  • model: the Engee model.

generate_executable_code(target::Target, model, is_ext_mode::Bool, verbose::Bool=false)::TargetResponse

A function designed to generate the source code of a model for subsequent assembly.

Arguments

  • target::Target: target instance.

  • model: the Engee model (for example, via engee.gcm()).

  • is_ext_mode::Bool: startup mode (external mode - interactive mode, or independent mode).

  • verbose::Bool=false: printing additional information during generation.

start_model(
    target::Target,
    model,
    is_ext_mode::Bool;
    simulation_uuid::String=string(uuid4()),
    status_callback::Function=((args...) -> nothing),
    termination_callback::Function=((args...) -> nothing),
)::Union{Channel{TargetSimulationStatus},Nothing}

A function designed to launch the target model.

Arguments

  • target::Target: target instance.

  • model: model Engee.

  • is_ext_mode::Bool: startup mode (external mode - interactive mode, or independent mode).

  • simulation_uuid::String: The UUID of the simulation.

  • status_callback::Function: the callback that is called on each status message.

  • termination_callback::Function: the callback called at the end of the read cycle.

stop_model(target::Target)::TargetResponse

A function designed to stop the model from working on the target.

Arguments

  • target::Target: target instance.

upload_model(target::Target, model)::TargetResponse

A function designed to upload the compiled model to the target.

Arguments

  • target::Target: target instance.

  • model: model Engee.

wait_model_to_complete(
    channel::Channel{TargetSimulationStatus},
    timeout_seconds::Real = 60,
)::Tuple{Bool,Float64}

The function of waiting for the completion of the model in interactive mode.

Arguments

  • channel::Channel{TargetSimulationStatus}: status channel returned start_model or build_deploy_start in interactive mode.

  • timeout_seconds::Real=60: waiting time in seconds.

change_param(target::Target, block_path::String, value_name::String, data::Union{Int64, Float64, Bool, Vector{Int64}, Vector{Float64}, Vector{Bool}})::TargetResponse

A function designed to change the parameter of a block of a model running interactively. It must be called during the operation of the model.

Arguments

  • target::Target: target instance.

  • block_path: path to the block Engee.

  • value_name::String: the name of the block parameter to change.

  • data::Union{Int64, Float64, Bool, Vector{Int64}, Vector{Float64}, Vector{Bool}}: data to be written to the parameter.

Examples

change_param(target, engee.gcb(), "Value", 4)

Changes the parameter Value The current block is set to 4.

Before calling, you must hover the cursor over the block whose parameter value you want to change, or instead of engee.gcb() specify the path to a specific block.

is_ext_mode

Flag is_ext_mode sets the execution mode:

  • false — independent mode; start_model(…​) it only runs the model and returns nothing;

  • true — interactive mode; start_model(…​)/build_deploy_start(…​) They are returning Channel{TargetSimulationStatus} for monitoring statuses.

Completing the model execution

For interactive mode, use the channel returned by start_model or build_deploy_start:

channel = Targets.build_deploy_start(target, model, is_external_mode=true)
success, elapsed = Targets.wait_model_to_complete(channel, 120)

  • success == true — the model has ended (the channel has closed);

  • success == false — we went out on timeout.

Callbacks in start_model / build_deploy_start

You can send:

  • status_callback(status::TargetSimulationStatus) — called at every status message;

  • termination_callback() — it is called once at the end of the status/data reading cycle.

status in the callback, it has the type TargetSimulationStatus and fields:

  • status::String — the state of the model (usually running, final — done or error; completion is determined by the transition from running to a different state);

  • model_time::Float64 — model time on target;

  • progress::Float64 — progress (usually in the range of 0–1);

  • detail::String — additional text information.

Example:

function status_cb(status)
    println("status=$(status.status), progress=$(status.progress)")
end

function done_cb()
    println("simulation finished")
end

channel = Targets.start_model(
    target, model, true;
    status_callback=status_cb,
    termination_callback=done_cb,
)

If the callback throws an exception, the execution of the model will not be interrupted: the callback error is logged as a warning.

Exceptions

All target management functions (generate_executable_code, compile_model, upload_model, start_model, stop_model, build_deploy_start) may throw exceptions in case of generation, build, download, launch, target connection, etc. errors. Exceptions must be handled on the calling code’s side (for example, via try/catch).

TargetResponse — a structure containing an information message about the status of the function.

An example of running a model on an STM32 in independent mode

using Main.EngeeDeviceManager.Targets
using Main.EngeeDeviceManager.Targets.STM32
model = engee.gcm()
target = STM32.Stm32()

is_external_mode = false

# Functions for programmatic target management:

Targets.generate_executable_code(target, model, is_external_mode)
Targets.compile_model(target, model)
Targets.upload_model(target, model)
Targets.start_model(target, model, is_external_mode)
Targets.stop_model(target)

Alternatively, you can use one function, instead of the four presented, to generate code, build, upload compiled code to the target and run the model on it.:

Targets.build_deploy_start(target, model, is_external_mode=is_external_mode)