Engee documentation

EULER software control

This page presents all available EULER software control functions in Engee.

To work with EULER software control functions in Engee. install the hardware support package as specified in article. After installation, run:

using Main.EngeeDeviceManager.EULER_API

Next, you need to create a session object:

session = EULER_API.createSession()

All methods take the first argument session — session object.

Status codes are not sent out: if an error occurs, the method throws an exception with its description.

 
EULER_API.closeProject(session) -> Nothing

Closes the currently open project. Frees up the project’s resources, but the session remains active.

An exception is thrown if an error occurs.

EULER_API.closeSession(session) -> Nothing

Terminates the session with EILER. Frees all resources and closes the solver. After calling this function, the object session is no longer valid.

Arguments

  • session::Tuple{Main.EngeeDeviceManager.EULER_API.EulerSession} : session object.

EULER_API.createSession(euler_path::String="") -> session

Creates a session for working with the EULER solver. Initialises the solver core.

Returns session::Tuple{Main.EngeeDeviceManager.EULER_API.EulerSession}-- the session object, which is passed to all other methods.euler_path::String: the path to the EYLER executable. By default, euler_path="" — auto-detection.

EULER_API.getCurrentTime(session) -> Float64

Returns the current model time in seconds.

Arguments

  • session::Tuple{Main.EngeeDeviceManager.EULER_API.EulerSession} : session object.

EULER_API.getLastProject(session) -> String

Returns the full path to the .elr file of the latest EULER project. Useful for restoring the state after a restart.

Arguments

  • session::Tuple{Main.EngeeDeviceManager.EULER_API.EulerSession} : session object.

EULER_API.getRigidBodyCount(session) -> Int

Returns the number of solid bodies in the current project.

Arguments

  • session::Tuple{Main.EngeeDeviceManager.EULER_API.EulerSession} : session object.

EULER_API.getRigidBodyPos(session, index=0) -> Vector{Float64}

Returns an array of 12 elements: the centre-of-mass coordinates (X, Y, Z) and a 3×3 orientation matrix (9 elements, column-oriented).

Arguments

  • session::Tuple{Main.EngeeDeviceManager.EULER_API.EulerSession} : session object.

  • index::Int64: solid body index; indexing starts from 0. By default, 0.

EULER_API.getSensorUnits(session, name) -> String

Returns a string containing the sensor’s units of measurement in the SI system based on its name, for example, "Н", "м", "м/с".

Arguments

  • session::Tuple{Main.EngeeDeviceManager.EULER_API.EulerSession} : session object.

  • name::String : sensor name.

EULER_API.getSensorValue(session, name) -> Float64

Returns the current value of the sensor by name in SI units. The value corresponds to the most recent calculated data point.

An exception is thrown if an error occurs.

Arguments

  • : session object.

  • name::String: sensor name (e.g., "fx_sensor", "X", "Y").

EULER_API.getUserCommands(session) -> String

Returns a string containing the names of available user commands. Commands are separated by the '``";"` ’ character. Available in any mode after opening a project.

Arguments

  • session::Tuple{Main.EngeeDeviceManager.EULER_API.EulerSession} : session object.

EULER_API.getVersion(session) -> String

Returns the version of the EYLER solver as a string (for example, "13.05.43").

Arguments

  • session::Tuple{Main.EngeeDeviceManager.EULER_API.EulerSession} : session object.

EULER_API.journalLoadPoint(session, index) -> Nothing

Loads the log point by index into the current context. After loading, getSensorValue will return the sensor values for this point, rather than for the last calculated one.

An exception is thrown on error.

Arguments

  • session::Tuple{Main.EngeeDeviceManager.EULER_API.EulerSession} : session object.

  • index::Int64: point index (indexes are numbered starting from 0).

EULER_API.journalSensorValues(session, name) -> Vector{Float64}

Returns an array of sensor values at all points in the calculation log in chronological order.

An exception is thrown if an error occurs.

Arguments

  • session::Tuple{Main.EngeeDeviceManager.EULER_API.EulerSession} : session object.

  • name::String : sensor name.

EULER_API.journalSize(session) -> Int

Returns the number of points stored in the calculation log. The value 0 corresponds to an empty log.

Arguments

  • session::Tuple{Main.EngeeDeviceManager.EULER_API.EulerSession} : session object.

EULER_API.journalTime(session, index) -> Float64

Returns the model time in seconds for the log point at the specified index.

Arguments

session object.

  • index::Int64: point index (indexes start at 0).

EULER_API.openProject(session, path) -> String

Opens an EILER project (an .elr file). Once opened, commands, sensors and parameters become available. Returns the path to the loaded project as a string; an exception is thrown if an error occurs.

Arguments

  • session::Tuple{Main.EngeeDeviceManager.EULER_API.EulerSession} : session object.

  • path::String : full path to the .elr file.

EULER_API.runAnyCommand(session, command, step=1) -> Nothing

Runs a user-defined command without a time limit. The calculation runs until the command naturally completes. Available in exploration mode only.

An exception is thrown if an error occurs.

Arguments

  • session::Tuple{Main.EngeeDeviceManager.EULER_API.EulerSession} : session object.

  • command::String : command name.

  • step::Int64: output step. By default, 1.

EULER_API.runCommand(session, command, calc_time=10.0, step=1.0) -> Nothing

Runs a user command with a time limit. The calculation will stop when calc_time seconds of model time have elapsed or when the command completes — whichever comes first. Available only in exploration mode (setCalcRegime).

An exception is thrown if an error occurs.

Arguments

  • session::Tuple{Main.EngeeDeviceManager.EULER_API.EulerSession} : session object.

  • command::String: command name (from the list getUserCommands).

  • calc_time::Float64: maximum calculation duration in seconds of model time. By default: 10.0.

  • step::Float64: output step for this command. By default, 1.0 (every integrator step).

EULER_API.saveProject(session) -> Nothing

Saves the current project. Changes are written to the original .elr file.

An exception is thrown if an error occurs.

Arguments

  • session::Tuple{Main.EngeeDeviceManager.EULER_API.EulerSession} : the session object.

EULER_API.saveResults(session, path) -> Nothing

Saves the calculation results to an .epp (Euler Project Package) file.

An exception is thrown if an error occurs.

Arguments

  • session::Tuple{Main.EngeeDeviceManager.EULER_API.EulerSession} : session object.

  • path::String : path to save the .epp file.

EULER_API.setCalcRegime(session) -> Nothing

Переводит проект в режим исследования (расчета). В этом режиме доступен запуск команд (runCommand, runAnyCommand) и чтение датчиков. Изменение скаляров недоступно.

При ошибке выбрасывается исключение.

Аргументы

  • session::Tuple{Main.EngeeDeviceManager.EULER_API.EulerSession}: объект сеанса.

EULER_API.setEditRegime(session) -> Nothing

Switches the project to edit mode. In this mode, parameters (scalars) can be modified via setScalar. Running a calculation is not possible.

An exception is thrown if an error occurs.

Arguments

  • session::Tuple{Main.EngeeDeviceManager.EULER_API.EulerSession} : session object.

EULER_API.setOutputParam(session, step_out=1, time_out=0.0, before_event=false, after_event=false) -> Nothing

Configures the parameters for outputting results to the calculation log.

An exception is thrown if an error occurs.

Arguments

  • session::Tuple{Main.EngeeDeviceManager.EULER_API.EulerSession} : session object.

  • step_out::Int64: output step. Every Nth calculation point is included in the log. By default, 1.

  • time_out::Float64: output frequency in model time, in seconds. By default, 0.0 (disabled; only step_out is used).

  • before_event::Bool: whether to save a point before an event. By default, false — do not save.

  • after_event::Bool: whether to save a point after an event. By default, false — do not save.

EULER_API.setCalcRegime(session) -> Nothing

Puts the project into exploration (calculation) mode. In this mode, it is possible to run commands (runCommand, runAnyCommand) and read sensors. Modifying scalars is not permitted.

An exception is thrown if an error occurs.

@binding: Main.EngeeDeviceManager.EULERAPI.setCalcRegime @typesig: Tuple{Main.EngeeDeviceManager.EULERAPI.EulerSession}

Sets the value of a scalar parameter by name. Only available in edit mode (setEditRegime).

An exception is thrown if an error occurs.

Arguments

  • session::Tuple{Main.EngeeDeviceManager.EULER_API.EulerSession} : the session object.

  • name::String: the name of the scalar (e.g., "FX", "mass").

  • value::Float64 : the new value of the scalar.

EULER_API.startCalc(session) -> Nothing

Resets the model time to 0.0 (start position) and initialises the calculation. Called once before the first command runCommand or runAnyCommand.

An exception is thrown if an error occurs.

Arguments

  • session::Tuple{Main.EngeeDeviceManager.EULER_API.EulerSession} : session object.

EULER_API.stopCalc(session) -> Nothing

Stops the current calculation. Can be called at any time after running runCommand or runAnyCommand. The time of the stop can be obtained via getCurrentTime.

An exception is thrown if an error occurs.

Arguments

  • session::Tuple{Main.EngeeDeviceManager.EULER_API.EulerSession} : session object.

Operating modes

After opening, the project is in editing mode — you can open/close the project, change the parameters (scalars) via setScalar. Starting the calculation in this mode is not available. To run the model, switch to research mode (setCalcRegime), after which it becomes possible to run commands (runCommand, runAnyCommand) and reading the sensors during the calculation process (getSensorValue, journalSensorValues), but changing scalars will be blocked. Switching between modes is performed via setEditRegime and setCalcRegime.

Example: simulation of a ball throw with a mass of 1 kg and a diameter of 20 cm with a visualization of the trajectory

After installation hardware support package execute:

using Main.EngeeDeviceManager
using Main.EngeeDeviceManager.EULER_API
using Main.EngeeDeviceManager.UTILS_API

Creating a session:

session = EULER_API.createSession()
ver = EULER_API.getVersion(session)
println("Версия ЭЙЛЕР: $ver")
Версия ЭЙЛЕР: Solver 13.05.43.beta Pro (Windows x64)

Uploading a test project:

engee.package.getdemos("Engee-Device-Manager")
"/user/Engee-Device-Manager-demos"

First, copy the test one.elr file from the demo folder Engee to the user’s computer via the module Utils:

# Создаем объект Utils для файловых операций
utils = UTILS_API.Utils()

# Определяем пути к демонстрационному проект ЭЙЛЕР в Engee и директории, куда будет скопирован проект
euler_local_project_path = "/user/Engee-Device-Manager-demos/example_euler/sample_project.elr"
host_project_dir = raw"C:\Users\Public\Engee"

# Создаем тестовую директорию и загружаем проект на хост
UTILS_API.createFolder(utils, host_project_dir, "")
UTILS_API.uploadFile(utils, euler_local_project_path, host_project_dir)

println("Проект загружен в $host_project_dir")
Проект загружен в C:\Users\Public\Engee

Opening the project and starting the calculation:

# Открываем проект
project_path = joinpath(host_project_dir, "sample_project.elr")
EULER_API.openProject(session, project_path)
println("Проект открыт: $project_path")

# Получаем список доступных команд
cmds = EULER_API.getUserCommands(session)
println("Доступные команды: $cmds")

# Переключаем в режим исследования проекта
EULER_API.setCalcRegime(session)
println("Режим исследования проекта")

# Настраиваем вывод каждого 10-го шага
EULER_API.setOutputParam(session, 10, 0.0)

# Запускаем расчет на 15 секунд
EULER_API.runCommand(session, "RK4_coarse", 15.0)
println("Расчет запущен")
Проект открыт: C:\Users\Public\Engee/sample_project.elr
Доступные команды: RK4_fine;RK4_coarse;
Режим исследования проекта
Расчет запущен

Getting results:

# Получаем все точки из журнала расчета
x_vals = EULER_API.journalSensorValues(session, "X")
y_vals = EULER_API.journalSensorValues(session, "Y")

n_points = length(x_vals)
println("Получено $n_points точек")

# Выводим первые и последние точки
println("Первая точка: X=$(round(x_vals[1], digits=2)) м, Y=$(round(y_vals[1], digits=2)) м")
if n_points > 1
    println("Последняя точка: X=$(round(x_vals[end], digits=2)) м, Y=$(round(y_vals[end], digits=2)) м")
end
Получено 1447 точек
Первая точка: X=0.0 м, Y=0.0 м
Последняя точка: X=1019.72 м, Y=-0.0 м

Visualization of the trajectory:

using Plots

# Получаем время каждой точки (значения датчик "t")
t_vals = EULER_API.journalSensorValues(session, "t")

# График высоты от времени
plot(t_vals, y_vals,
    xlabel = "Время, с",
    ylabel = "Высота Y, м",
    title = "Траектория броска шара
    D = 20 см
    m = 1 кг",
    legend = false,
    linewidth = 2,
    color = :blue,
    size = (600, 400)
)

hline!([0.0], color = :orange, linewidth = 1, linestyle = :dash, label = "Земля")

euler functions 1

Completion of work:

EULER_API.closeSession(session)
println("Сеанс завершен")
The session is over