added s-function mask (#926)

Co-authored-by: Leonardo <leonardo.cecchin@de.bosch.com>

docs/matlab_octave_interface/index.md

@@ -66,6 +66,30 @@ A more advanced Simulink example which showcases how to customize the inputs and
 
 If you want a more advanced interaction with the `acados` solver via Simulink, feel free to edit the corresponding templates in [`<acados_root>/interfaces/acados_template/acados_template/c_templates_tera`](https://github.com/acados/acados/tree/master/interfaces/acados_template/acados_template/c_templates_tera) to add more inputs or outputs.
 
+### S-function Mask
+The simulink S-functions interface can be improved using the following mask commands, which shows the names of input and output ports, facilitating debugging operations.
+These commands use global variables that are automatically generated by the `make_sfun` command.
+1. OCP S-function mask
+```
+global sfun_input_names sfun_output_names
+for i = 1:length(sfun_input_names)
+	port_label('input', i, sfun_input_names{i})
+end
+for i = 1:length(sfun_output_names)
+	port_label('output', i, sfun_output_names{i})
+end
+```
+2. SIM S-function mask
+```
+global sfun_sim_input_names sfun_sim_output_names
+for i = 1:length(sfun_sim_input_names)
+	port_label('input', i, sfun_sim_input_names{i})
+end
+for i = 1:length(sfun_sim_output_names)
+	port_label('output', i, sfun_sim_output_names{i})
+end
+```
+To use the mask command just copy-paste it in the "icon drawing commands" field, accessible by right clicking on the S-function block - Mask - Edit Mask.
 
 ## Setup CasADi
 To create external function for your problem, we suggest to use `CasADi` from the folder `<acados_root_folder>/external`.

interfaces/acados_template/acados_template/c_templates_tera/matlab_templates/make_sfun.in.m

@@ -178,128 +178,154 @@
     eval('mexext')] );
 
 
-%% print note on usage of s-function
+%% print note on usage of s-function, and create I/O port names vectors
 fprintf('\n\nNote: Usage of Sfunction is as follows:\n')
 input_note = 'Inputs are:\n';
 i_in = 1;
 
+global sfun_input_names
+sfun_input_names = {};
 
 {%- if dims.nbx_0 > 0 and simulink_opts.inputs.lbx_0 -%}  {#- lbx_0 #}
 input_note = strcat(input_note, num2str(i_in), ') lbx_0 - lower bound on x for stage 0,',...
                     ' size [{{ dims.nbx_0 }}]\n ');
+sfun_input_names = [sfun_input_names; 'lbx_0 [{{ dims.nbx_0 }}]'];
 i_in = i_in + 1;
 {%- endif %}
 
 {%- if dims.nbx_0 > 0 and simulink_opts.inputs.ubx_0 -%}  {#- ubx_0 #}
 input_note = strcat(input_note, num2str(i_in), ') ubx_0 - upper bound on x for stage 0,',...
                     ' size [{{ dims.nbx_0 }}]\n ');
+sfun_input_names = [sfun_input_names; 'ubx_0 [{{ dims.nbx_0 }}]'];
 i_in = i_in + 1;
 {%- endif %}
 
 {%- if dims.np > 0 and simulink_opts.inputs.parameter_traj -%}  {#- parameter_traj #}
 input_note = strcat(input_note, num2str(i_in), ') parameters - concatenated for all shooting nodes 0 to N+1,',...
                     ' size [{{ (dims.N+1)*dims.np }}]\n ');
+sfun_input_names = [sfun_input_names; 'parameter_traj [{{ (dims.N+1)*dims.np }}]'];
 i_in = i_in + 1;
 {%- endif %}
 
 {%- if dims.ny_0 > 0 and simulink_opts.inputs.y_ref_0 %}
 input_note = strcat(input_note, num2str(i_in), ') y_ref_0, size [{{ dims.ny_0 }}]\n ');
+sfun_input_names = [sfun_input_names; 'y_ref_0 [{{ dims.ny_0 }}]'];
 i_in = i_in + 1;
 {%- endif %}
 
 {%- if dims.ny > 0 and dims.N > 1 and simulink_opts.inputs.y_ref %}
 input_note = strcat(input_note, num2str(i_in), ') y_ref - concatenated for shooting nodes 1 to N-1,',...
                     ' size [{{ (dims.N-1) * dims.ny }}]\n ');
+sfun_input_names = [sfun_input_names; 'y_ref [{{ (dims.N-1) * dims.ny }}]'];
 i_in = i_in + 1;
 {%- endif %}
 
 {%- if dims.ny_e > 0 and dims.N > 0 and simulink_opts.inputs.y_ref_e %}
 input_note = strcat(input_note, num2str(i_in), ') y_ref_e, size [{{ dims.ny_e }}]\n ');
+sfun_input_names = [sfun_input_names; 'y_ref_e [{{ dims.ny_e }}]'];
 i_in = i_in + 1;
 {%- endif %}
 
 {%- if dims.nbx > 0 and dims.N > 1 and simulink_opts.inputs.lbx -%}  {#- lbx #}
 input_note = strcat(input_note, num2str(i_in), ') lbx for shooting nodes 1 to N-1, size [{{ (dims.N-1) * dims.nbx }}]\n ');
+sfun_input_names = [sfun_input_names; 'lbx [{{ (dims.N-1) * dims.nbx }}]'];
 i_in = i_in + 1;
 {%- endif %}
 {%- if dims.nbx > 0 and dims.N > 1 and simulink_opts.inputs.ubx -%}  {#- ubx #}
 input_note = strcat(input_note, num2str(i_in), ') ubx for shooting nodes 1 to N-1, size [{{ (dims.N-1) * dims.nbx }}]\n ');
+sfun_input_names = [sfun_input_names; 'ubx [{{ (dims.N-1) * dims.nbx }}]'];
 i_in = i_in + 1;
 {%- endif %}
 
 
 {%- if dims.nbx_e > 0 and dims.N > 0 and simulink_opts.inputs.lbx_e -%}  {#- lbx_e #}
 input_note = strcat(input_note, num2str(i_in), ') lbx_e (lbx at shooting node N), size [{{ dims.nbx_e }}]\n ');
+sfun_input_names = [sfun_input_names; 'lbx_e [{{ dims.nbx_e }}]'];
 i_in = i_in + 1;
 {%- endif %}
 {%- if dims.nbx_e > 0 and dims.N > 0 and simulink_opts.inputs.ubx_e -%}  {#- ubx_e #}
 input_note = strcat(input_note, num2str(i_in), ') ubx_e (ubx at shooting node N), size [{{ dims.nbx_e }}]\n ');
+sfun_input_names = [sfun_input_names; 'ubx_e [{{ dims.nbx_e }}]'];
 i_in = i_in + 1;
 {%- endif %}
 
 {%- if dims.nbu > 0 and dims.N > 0 and simulink_opts.inputs.lbu -%}  {#- lbu #}
 input_note = strcat(input_note, num2str(i_in), ') lbu for shooting nodes 0 to N-1, size [{{ dims.N*dims.nbu }}]\n ');
+sfun_input_names = [sfun_input_names; 'lbu [{{ dims.N*dims.nbu }}]'];
 i_in = i_in + 1;
 {%- endif -%}
 {%- if dims.nbu > 0 and dims.N > 0 and simulink_opts.inputs.ubu -%}  {#- ubu #}
 input_note = strcat(input_note, num2str(i_in), ') ubu for shooting nodes 0 to N-1, size [{{ dims.N*dims.nbu }}]\n ');
+sfun_input_names = [sfun_input_names; 'ubu [{{ dims.N*dims.nbu }}]'];
 i_in = i_in + 1;
 {%- endif -%}
 
 {%- if dims.ng > 0 and simulink_opts.inputs.lg -%}  {#- lg #}
 input_note = strcat(input_note, num2str(i_in), ') lg for shooting nodes 0 to N-1, size [{{ dims.N*dims.ng }}]\n ');
+sfun_input_names = [sfun_input_names; 'lg [{{ dims.N*dims.ng }}]'];
 i_in = i_in + 1;
 {%- endif %}
 {%- if dims.ng > 0 and simulink_opts.inputs.ug -%}  {#- ug #}
 input_note = strcat(input_note, num2str(i_in), ') ug for shooting nodes 0 to N-1, size [{{ dims.N*dims.ng }}]\n ');
+sfun_input_names = [sfun_input_names; 'ug [{{ dims.N*dims.ng }}]'];
 i_in = i_in + 1;
 {%- endif %}
 
 {%- if dims.nh > 0 and simulink_opts.inputs.lh -%}  {#- lh #}
 input_note = strcat(input_note, num2str(i_in), ') lh for shooting nodes 0 to N-1, size [{{ dims.N*dims.nh }}]\n ');
+sfun_input_names = [sfun_input_names; 'lh [{{ dims.N*dims.nh }}]'];
 i_in = i_in + 1;
 {%- endif %}
 {%- if dims.nh > 0 and simulink_opts.inputs.uh -%}  {#- uh #}
 input_note = strcat(input_note, num2str(i_in), ') uh for shooting nodes 0 to N-1, size [{{ dims.N*dims.nh }}]\n ');
+sfun_input_names = [sfun_input_names; 'uh [{{ dims.N*dims.nh }}]'];
 i_in = i_in + 1;
 {%- endif %}
 
 {%- if dims.nh_e > 0 and simulink_opts.inputs.lh_e -%}  {#- lh_e #}
 input_note = strcat(input_note, num2str(i_in), ') lh_e, size [{{ dims.nh_e }}]\n ');
+sfun_input_names = [sfun_input_names; 'lh_e [{{ dims.nh_e }}]'];
 i_in = i_in + 1;
 {%- endif %}
 {%- if dims.nh_e > 0 and simulink_opts.inputs.uh_e -%}  {#- uh_e #}
 input_note = strcat(input_note, num2str(i_in), ') uh_e, size [{{ dims.nh_e }}]\n ');
+sfun_input_names = [sfun_input_names; 'uh_e [{{ dims.nh_e }}]'];
 i_in = i_in + 1;
 {%- endif %}
 
 {%- if dims.ny_0 > 0 and simulink_opts.inputs.cost_W_0 %}  {#- cost_W_0 #}
 input_note = strcat(input_note, num2str(i_in), ') cost_W_0 in column-major format, size [{{ dims.ny_0 * dims.ny_0 }}]\n ');
+sfun_input_names = [sfun_input_names; 'cost_W_0 [{{ dims.ny_0 * dims.ny_0 }}]'];
 i_in = i_in + 1;
 {%- endif %}
 
 {%- if dims.ny > 0 and simulink_opts.inputs.cost_W %}  {#- cost_W #}
 input_note = strcat(input_note, num2str(i_in), ') cost_W in column-major format, that is set for all intermediate shooting nodes: 1 to N-1, size [{{ dims.ny * dims.ny }}]\n ');
+sfun_input_names = [sfun_input_names; 'cost_W [{{ dims.ny * dims.ny }}]'];
 i_in = i_in + 1;
 {%- endif %}
 
 {%- if dims.ny_e > 0 and simulink_opts.inputs.cost_W_e %}  {#- cost_W_e #}
 input_note = strcat(input_note, num2str(i_in), ') cost_W_e in column-major format, size [{{ dims.ny_e * dims.ny_e }}]\n ');
+sfun_input_names = [sfun_input_names; 'cost_W_e [{{ dims.ny_e * dims.ny_e }}]'];
 i_in = i_in + 1;
 {%- endif %}
 
 {%- if simulink_opts.inputs.reset_solver %}  {#- reset_solver #}
 input_note = strcat(input_note, num2str(i_in), ') reset_solver determines if iterate is set to all zeros before other initializations (x_init, u_init) are set and before solver is called, size [1]\n ');
+sfun_input_names = [sfun_input_names; 'reset_solver [1]'];
 i_in = i_in + 1;
 {%- endif %}
 
 {%- if simulink_opts.inputs.x_init %}  {#- x_init #}
 input_note = strcat(input_note, num2str(i_in), ') initialization of x for all shooting nodes, size [{{ dims.nx * (dims.N+1) }}]\n ');
+sfun_input_names = [sfun_input_names; 'x_init [{{ dims.nx * (dims.N+1) }}]'];
 i_in = i_in + 1;
 {%- endif %}
 
 {%- if simulink_opts.inputs.u_init %}  {#- u_init #}
 input_note = strcat(input_note, num2str(i_in), ') initialization of u for shooting nodes 0 to N-1, size [{{ dims.nu * (dims.N) }}]\n ');
+sfun_input_names = [sfun_input_names; 'u_init [{{ dims.nu * (dims.N) }}]'];
 i_in = i_in + 1;
 {%- endif %}
 
@@ -310,70 +336,99 @@
 output_note = 'Outputs are:\n';
 i_out = 0;
 
+global sfun_output_names
+sfun_output_names = {};
+
 {%- if dims.nu > 0 and simulink_opts.outputs.u0 == 1 %}
 i_out = i_out + 1;
 output_note = strcat(output_note, num2str(i_out), ') u0, control input at node 0, size [{{ dims.nu }}]\n ');
+sfun_output_names = [sfun_output_names; 'u0 [{{ dims.nu }}]'];
 {%- endif %}
 
 {%- if simulink_opts.outputs.utraj == 1 %}
 i_out = i_out + 1;
 output_note = strcat(output_note, num2str(i_out), ') utraj, control input concatenated for nodes 0 to N-1, size [{{ dims.nu * dims.N }}]\n ');
+sfun_output_names = [sfun_output_names; 'utraj [{{ dims.nu * dims.N }}]'];
 {%- endif %}
 
 {%- if simulink_opts.outputs.xtraj == 1 %}
 i_out = i_out + 1;
 output_note = strcat(output_note, num2str(i_out), ') xtraj, state concatenated for nodes 0 to N, size [{{ dims.nx * (dims.N + 1) }}]\n ');
+sfun_output_names = [sfun_output_names; 'xtraj [{{ dims.nx * (dims.N + 1) }}]'];
 {%- endif %}
 
 {%- if simulink_opts.outputs.solver_status == 1 %}
 i_out = i_out + 1;
 output_note = strcat(output_note, num2str(i_out), ') acados solver status (0 = SUCCESS)\n ');
+sfun_output_names = [sfun_output_names; 'solver_status'];
 {%- endif %}
 
 {%- if simulink_opts.outputs.cost_value == 1 %}
 i_out = i_out + 1;
 output_note = strcat(output_note, num2str(i_out), ') cost function value\n ');
+sfun_output_names = [sfun_output_names; 'cost_value'];
 {%- endif %}
 
 
 {%- if simulink_opts.outputs.KKT_residual == 1 %}
 i_out = i_out + 1;
 output_note = strcat(output_note, num2str(i_out), ') KKT residual\n ');
+sfun_output_names = [sfun_output_names; 'KKT_residual'];
 {%- endif %}
 
 {%- if simulink_opts.outputs.KKT_residuals == 1 %}
 i_out = i_out + 1;
 output_note = strcat(output_note, num2str(i_out), ') KKT residuals, size [4] (stat, eq, ineq, comp)\n ');
+sfun_output_names = [sfun_output_names; 'KKT_residuals [4]'];
 {%- endif %}
 
 {%- if dims.N > 0 and simulink_opts.outputs.x1 == 1 %}
 i_out = i_out + 1;
 output_note = strcat(output_note, num2str(i_out), ') x1, state at node 1\n ');
+sfun_output_names = [sfun_output_names; 'x1'];
 {%- endif %}
 
 {%- if simulink_opts.outputs.CPU_time == 1 %}
 i_out = i_out + 1;
 output_note = strcat(output_note, num2str(i_out), ') CPU time\n ');
+sfun_output_names = [sfun_output_names; 'CPU_time'];
 {%- endif %}
 
 {%- if simulink_opts.outputs.CPU_time_sim == 1 %}
 i_out = i_out + 1;
 output_note = strcat(output_note, num2str(i_out), ') CPU time integrator\n ');
+sfun_output_names = [sfun_output_names; 'CPU_time_sim'];
 {%- endif %}
 
 {%- if simulink_opts.outputs.CPU_time_qp == 1 %}
 i_out = i_out + 1;
 output_note = strcat(output_note, num2str(i_out), ') CPU time QP solution\n ');
+sfun_output_names = [sfun_output_names; 'CPU_time_qp'];
 {%- endif %}
 
 {%- if simulink_opts.outputs.CPU_time_lin == 1 %}
 i_out = i_out + 1;
 output_note = strcat(output_note, num2str(i_out), ') CPU time linearization (including integrator)\n ');
+sfun_output_names = [sfun_output_names; 'CPU_time_lin'];
 {%- endif %}
 
 {%- if simulink_opts.outputs.sqp_iter == 1 %}
 i_out = i_out + 1;
 output_note = strcat(output_note, num2str(i_out), ') SQP iterations\n ');
+sfun_output_names = [sfun_output_names; 'sqp_iter'];
 {%- endif %}
 
 fprintf(output_note)
+
+% The mask drawing command is:
+% ---
+% global sfun_input_names sfun_output_names
+% for i = 1:length(sfun_input_names)
+% 	port_label('input', i, sfun_input_names{i})
+% end
+% for i = 1:length(sfun_output_names)
+% 	port_label('output', i, sfun_output_names{i})
+% end
+% ---
+% It can be used by copying it in sfunction/Mask/Edit mask/Icon drawing commands
+%   (you can access it wirth ctrl+M on the s-function)

interfaces/acados_template/acados_template/c_templates_tera/matlab_templates/make_sfun_sim.in.m

@@ -89,26 +89,51 @@
     eval('mexext')] );
 
 
+global sfun_sim_input_names
+sfun_sim_input_names = {};
+
 %% print note on usage of s-function
 fprintf('\n\nNote: Usage of Sfunction is as follows:\n')
 input_note = 'Inputs are:\n1) x0, initial state, size [{{ dims.nx }}]\n ';
 i_in = 2;
+sfun_sim_input_names = [sfun_sim_input_names; 'x0 [{{ dims.nx }}]'];
+
 {%- if dims.nu > 0 %}
 input_note = strcat(input_note, num2str(i_in), ') u, size [{{ dims.nu }}]\n ');
 i_in = i_in + 1;
+sfun_sim_input_names = [sfun_sim_input_names; 'u [{{ dims.nu }}]'];
 {%- endif %}
 
 {%- if dims.np > 0 %}
 input_note = strcat(input_note, num2str(i_in), ') parameters, size [{{ dims.np }}]\n ');
 i_in = i_in + 1;
+sfun_sim_input_names = [sfun_sim_input_names; 'p [{{ dims.np }}]'];
 {%- endif %}
 
 
 fprintf(input_note)
 
 disp(' ')
 
+global sfun_sim_output_names
+sfun_sim_output_names = {};
+
 output_note = strcat('Outputs are:\n', ...
                 '1) x1 - simulated state, size [{{ dims.nx }}]\n');
+sfun_sim_output_names = [sfun_sim_output_names; 'x1 [{{ dims.nx }}]'];
 
 fprintf(output_note)
+
+
+% The mask drawing command is:
+% ---
+% global sfun_sim_input_names sfun_sim_output_names
+% for i = 1:length(sfun_sim_input_names)
+% 	port_label('input', i, sfun_sim_input_names{i})
+% end
+% for i = 1:length(sfun_sim_output_names)
+% 	port_label('output', i, sfun_sim_output_names{i})
+% end
+% ---
+% It can be used by copying it in sfunction/Mask/Edit mask/Icon drawing commands
+%   (you can access it wirth ctrl+M on the s-function)