Adding states/information to the S-function outputs in JSBSim-Simulink integration

[Chris2814]

Hi,

I am currently setting up JSBSim with Matlab/Simulink to be used with system simulation of the flight control system. So far I've been successful with compiling and running JSBSim in Simulink, but I would want to access and output more information from JSBSim. For instance:

• Fuel flow
• Fuel mass
• Drag forces

And I would also like to be able to change the fuel mass during simulation (due to system power consumption simulated outside of JSBSim).

I've been trying to reverse engineer how the current information (states, pilot, control) is accessed and conveyed through the output ports of the S-function. My C++ knowledge is however not sufficient for figuring out how to access and convey the information listed above.

Are there any guidelines to be found on how to add, virtually any information used during the simulation, and add it to the vectors outputted from the S-function?

Thanks in advance!

Kind regards,
Christopher

[agodemar]

Hi @Chris2814 an important feature of JSBSim is the fact that the internal property tree is exposed to the user. The class JSBSimInterface provides the functions GetPropertyValue and SetPropertyValue that can be the way to go.
This requires you to get familiar with the structure of a MEX function, which you can use both in your Matlab command window or in you Simulink blocks.
You can have a look at this example project that I made back in 2009. In particular, I created a MEX function called MexJSBSim, designed to drive JSBSim from Matlab scripts. You can have a look at this function here.
An example of use of the MEX function is found here.
That could be a starting point for your customizations.

[seanmcleod]

@Chris2814 I'm no Matlab/MEX expert, haven't actually used the S-function feature, but glancing at the code you'll notice, first off that there are 4 output ports defined with a hard-coded set of JSBSim states that are output via the output ports.

if (!ssSetNumOutputPorts(S, 4)) return;

The first output port, index 0, is set as the port for the Discrete States

Output port 0 - Discrete States

ssSetNumDiscStates(S, 12);
ssSetOutputPortWidth(S, 0, 12);//The model has 12 states:[u v w p q r h-sl-ft long lat phi theta psi]	

Output port 1 - Flight controls output

/* Flight Controls output [thr-pos-norm left-ail-pos-rad right-ail-pos-rad el-pos-rad rud-pos-rad flap-pos-norm ]
   speedbrake-pos-rad spoiler-pos-rad gear-pos-norm] */

ssSetOutputPortWidth(S, 1, 9);

Output port 2 - Propulsion Outputs

/* Propulsion output piston (per engine) [prop-rpm prop-thrust-lbs mixture fuel-flow-gph advance-ratio power-hp pt-lbs_sqft 
 * volumetric-efficiency bsfc-lbs_hphr prop-torque blade-angle prop-pitch]
 * Propulsion output turbine (per engine) [thrust-lbs n1 n2 fuel-flow-pph fuel-flow-pps pt-lbs_sqft pitch-rad reverser-rad yaw-rad inject-cmd 
 * set-running fuel-dump]
 */

ssSetOutputPortWidth(S, 2, 48);  //currently not in use, could be defined later 

Output port 3 -

// Calculated outputs [pilot-Nz alpha alpha-dot beta beta-dot vc-fps vc-kts Vt-fps vg-fps mach climb-rate qbar-psf el-cmd-norm] 
ssSetOutputPortWidth(S, 3, 13);

I don't know enough about Matlab/Simulink to understand the distinction between the discrete states versus the other states that are output via the other output ports. But if you want to add additional states like drag forces etc. I guess the first thing to figure out/decide is which output port you're going to add the drag forces to. Then update the hard-coded values in terms of the relevant port width.

In terms of how these states are retrieved from JSBSim and added to the relevant output port take a look at the following:

jsbsim/matlab/JSBSimInterface.cpp

Lines 678 to 701 in d53cb46

	bool JSBSimInterface::Copy_States_From_JSBSim(double *state_array){
	// [u-fps v-fps w-fps p-radsec q-radsec r-radsec h-sl-ft long-gc-deg lat-gc-deg phi-rad theta-rad psi-rad]
	// Possibly add some error handling here?
	state_array[0] = propagate->GetUVW(1);
	state_array[1] = propagate->GetUVW(2);
	state_array[2] = propagate->GetUVW(3);
	state_array[3] = propagate->GetPQR(1);
	state_array[4] = propagate->GetPQR(2);
	state_array[5] = propagate->GetPQR(3);
	state_array[6] = propagate->GetAltitudeASLmeters();
	state_array[7] = propagate->GetLongitudeDeg();
	state_array[8] = propagate->GetLatitudeDeg();
	FGColumnVector3 euler = propagate->GetVState().qAttitudeLocal.GetEuler();
	state_array[9] = euler.Entry(1);
	state_array[10] = euler.Entry(2);
	state_array[11] = euler.Entry(3);
	return true;
	}

jsbsim/matlab/JSBSimInterface.cpp

Lines 703 to 726 in d53cb46

	bool JSBSimInterface::Copy_Pilot_From_JSBSim(double *state_array){
	// [N alpha alphadot beta betadot vc-fps vc-kts vt-fps vg-fps mach climb-rate qdyn-psf]
	// Possibly add some error handling here?
	state_array[0] = auxiliary->GetNlf(); // Normal load factor
	state_array[1] = auxiliary->Getalpha();
	state_array[2] = auxiliary->Getadot();
	state_array[3] = auxiliary->Getbeta();
	state_array[4] = auxiliary->Getbdot();
	state_array[5] = auxiliary->GetVcalibratedFPS(); //valibrated airspeed, fps
	state_array[6] = auxiliary->GetVcalibratedKTS(); //calibrated airspeed, knots
	state_array[7] = auxiliary->GetVtrueFPS(); //true airspeed, fps
	state_array[8] = auxiliary->GetVground(); //ground speed, fps
	state_array[9] = auxiliary->GetMach();
	state_array[10] = propagate->Gethdot();
	state_array[11] = auxiliary->Getqbar();
	state_array[12] = fcs->GetDeCmd(); //elevator cmd norm
	return true;
	}

jsbsim/matlab/JSBSimInterface.cpp

Lines 728 to 747 in d53cb46

	bool JSBSimInterface::Copy_Control_From_JSBSim(double *state_array){
	// [thr-pos-norm left-ail-pos-rad right-ail-pos-rad el-pos-rad rud-pos-rad flap-pos-norm ]
	// speedbrake-pos-rad spoiler-pos-rad gear-pos-norm]
	// Possibly add some error handling here?
	state_array[0] = fcs->GetThrottlePos(0); //should be an input command, NEEDS FIX
	state_array[1] = fcs->GetDaLPos(); //left aileron
	state_array[2] = fcs->GetDaRPos(); //right aileron
	state_array[3] = fcs->GetDePos(); //elevator
	state_array[4] = fcs->GetDrPos(); //rudder
	state_array[5] = fcs->GetDfPos(); //flaps
	state_array[6] = fcs->GetDsbPos(); //speedbrake
	state_array[7] = fcs->GetDspPos(); // spoiler
	state_array[8] = fcs->GetGearPos(); //gear
	return true;
	}

So once you've decided which output port you want to add your new states to, then you would edit the relevant method above to retrieve the state information from JSBSim and copy it to the relevant output port and index.

[agodemar]

@seanmcleod yes, I like your suggestion.
It could be a starting point to make a more general S-function. In Simulink you can decide whether or not to use an output port (signal). So, in principle one can add many output signal to make that Simulink block as general as possible. Then, the user will make a broad or limited use of the feature according to her needs.

[seanmcleod]

What I was wondering while glancing at the source code was whether you couldn't make the whole set of states and output ports dynamic in terms of reading a set of property names from a config file and use that to set up the output ports during initialization etc. and also use it during each time step to retrieve the property values from JSBSim.

That way any user who wanted to use the JSBSim S-Function with their own unique set of states could simply edit the config file and therefore wouldn't need to understand any C++ coding and wouldn't need to have to recompile the S-Function DLL.

When I first started looking at the source code in JSBSimInterface.cpp and I saw the JSBSimInterface::GetPropertyValue() method I assumed that the property lookup mechanism would be used to retrieve JSBSim state information, but it's not currently used in that way.

[agodemar]

@seanmcleod

When I first started looking at the source code in JSBSimInterface.cpp and I saw the JSBSimInterface::GetPropertyValue() method I assumed that the property lookup mechanism would be used to retrieve JSBSim state information, but it's not currently used in that way.

I created that function to make things general in case of future developments of the JSBSimInterface class. We are now at the point that we can start using it ;-)

[Chris2814]

Hi,

Thank you for your replies @agodemar and @seanmcleod, they are much appreciated!

So far I have managed to figure out how to change the outputs from the S-function. As you mentioned there are 4 output ports. The propulsion output port was previously not in use, but I managed to get it functioning and I currently use it as a "test output port".

I have observed the other output ports and how values are retrieved for the different elements of those output vectors. But I haven't really figured out how to, by the same measure, retrieve information using functions defined in other classes than those currently used. Allow me to elaborate with an example:

In the class FGFCS there are a bunch of different functions to be used for retrieving the position of various control surfaces (GetDePos, GetDrPos, GetDsbPos...). These functions are used and called upon to output the position of the control surfaces through the control output port in the S-function. I would like to be able to, in the same manner as for the FGFCS functions, call upon functions defined in other classes and output the returned values through the output ports in the S-function. For instance, in the class FGTank there is a function called "GetPctFull". The function returns the filled value of the tank in percent. I would like to be able to call on that function and output the returned value on one of the output ports in the S-function. I know how to change the output ports once the function is call-able, but my skills fail me when it comes to calling this function. Probably due to me not knowing where to modify the code more than at the definition of the output ports (JSBSimInterace.cpp).

I am somewhat familiar with the GetPropertyValue. I am however not aware if I can use it for the purpose described above. I suppose that the returned value from the GetPctFull function needs to be defined as a property somewhere for me to be able to retrieve it through the GetPropertyValue function? I found some native properties in the JSBSim manual. Those native properties where retrieve-able through the GetPropertyValue function at least :)

I like the idea of a configurable file! If time allows me in the future, perhaps that is something to start working on! :)

[seanmcleod]

In terms of properties they're defined/bound to methods typically in a bind() method. So for example here is the FGTank::bind() method from which you can see what properties are defined by the tank model.

You'll notice on line 465 a pct-full property is defined. Note that it's an indexed property since there can be multiple tanks.

jsbsim/src/models/propulsion/FGTank.cpp

Lines 454 to 489 in d53cb46

	void FGTank::bind(FGPropertyManager* PropertyManager)
	{
	string property_name, base_property_name;
	base_property_name = CreateIndexedPropertyName("propulsion/tank", TankNumber);
	property_name = base_property_name + "/contents-lbs";
	PropertyManager->Tie( property_name.c_str(), (FGTank*)this, &FGTank::GetContents,
	&FGTank::SetContents );
	property_name = base_property_name + "/unusable-volume-gal";
	PropertyManager->Tie( property_name.c_str(), (FGTank*)this, &FGTank::GetUnusableVolume,
	&FGTank::SetUnusableVolume );
	property_name = base_property_name + "/pct-full";
	PropertyManager->Tie( property_name.c_str(), (FGTank*)this, &FGTank::GetPctFull);
	property_name = base_property_name + "/density-lbs_per_gal";
	PropertyManager->Tie( property_name.c_str(), (FGTank*)this, &FGTank::GetDensity);
	property_name = base_property_name + "/priority";
	PropertyManager->Tie( property_name.c_str(), (FGTank*)this, &FGTank::GetPriority,
	&FGTank::SetPriority );
	property_name = base_property_name + "/external-flow-rate-pps";
	PropertyManager->Tie( property_name.c_str(), (FGTank*)this, &FGTank::GetExternalFlow,
	&FGTank::SetExternalFlow );
	property_name = base_property_name + "/local-ixx-slug_ft2";
	PropertyManager->Tie( property_name.c_str(), (FGTank*)this, &FGTank::GetIxx);
	property_name = base_property_name + "/local-iyy-slug_ft2";
	PropertyManager->Tie( property_name.c_str(), (FGTank*)this, &FGTank::GetIyy);
	property_name = base_property_name + "/local-izz-slug_ft2";
	PropertyManager->Tie( property_name.c_str(), (FGTank*)this, &FGTank::GetIzz);
	property_name = base_property_name + "/x-position";
	PropertyManager->Tie(property_name.c_str(), (FGTank*)this, &FGTank::GetLocationX, &FGTank::SetLocationX);
	property_name = base_property_name + "/y-position";
	PropertyManager->Tie(property_name.c_str(), (FGTank*)this, &FGTank::GetLocationY, &FGTank::SetLocationY);
	property_name = base_property_name + "/z-position";
	PropertyManager->Tie(property_name.c_str(), (FGTank*)this, &FGTank::GetLocationZ, &FGTank::SetLocationZ);
	}

[Chris2814]

Alright! Pieces begin to fall in place now.
This bind method explained a lot.

Thank you for your reply!