ForceSeatMI – Introductie | Next Level Racing

ForceSeatMI is een gebruiksvriendelijke maar krachtige interface waarmee je ondersteuning voor bewegingsplatforms kunt toevoegen aan elke applicatie of game (in de volgende secties SIM genoemd). In de meeste applicaties is het niet nodig om de hardware rechtstreeks vanuit de SIM aan te sturen. Daarom wordt ForceSeatMI alleen gebruikt om telemetrie- of positioneringsverzoeken naar ForceSeatPM te sturen. Deze aanpak delegeert de verantwoordelijkheid voor het omzetten van telemetriegegevens naar een daadwerkelijke platformbeweging van de SIM naar ForceSeatPM. Het vereenvoudigt ook de foutafhandeling die de SIM moet implementeren.

Met de nieuwste versie van ForceSeatMI is het mogelijk om de hardware aan te sturen met behulp van Inverse Kinematics. De SIM stuurt de gewenste positie van het bovenframe en ForceSeatPM berekent de vereiste posities van de armen (of actuatoren). Deze functie kan worden gebruikt in applicaties waar nauwkeurige positionering vereist is in plaats van krachten-simulatie.

Deze documentatie is alleen van toepassing op ForceSeatMI 2.63 of nieuwer. Oudere versies van de API worden niet in dit document behandeld. ForceSeatMI 2.63+ is ook niet achterwaarts compatibel op interface- en binair niveau met 2.61 en eerdere versies. Overstappen van een oudere ForceSeatMI naar 2.63+ vereist wijzigingen in de broncode van je applicatie.

Kenmerken

De SIM kan kiezen tussen verschillende bedrijfsmodi: krachten-simulatie (telemetrie), snelle positionering van het bovenframe en nauwkeurige positionering van het bovenframe
De SIM hoeft telemetriegegevens niet te vertalen naar een daadwerkelijke motorpositie – dit wordt gedaan door ForceSeatPM
De SIM is niet afhankelijk van specifieke bewegingsplatform-hardware; hardwaregerelateerde aanpassingen worden binnen ForceSeatPM gedaan
Alle diagnose- en verwerkingsfuncties van ForceSeatPM zijn nog steeds beschikbaar en kunnen worden gebruikt

Inhoud van het pakket

ForceSeatMI_Loader.c – een wrapper die functie-aanroepen doorstuurt naar de echte DLL (DLL wordt geïnstalleerd door ForceSeatPM)
ForceSeatMI_Common.h, ForceSeatMI_Common.cs – header met types en enums
ForceSeatMI_Functions.h – pure C/C++ API
ForceSeatMI.cs – C# API
ForceSeatMI_Telemetry.h, ForceSeatMI_Telemetry.cs – structuren voor telemetriegegevens
ForceSeatMI_Positioning.h, ForceSeatMI_Positioning.cs – structuren voor positioneringsgegevens
ForceSeatMI_TactileTransducers.h, ForceSeatMI_TactileTransducers.cs – structuren voor effecten van tactiele transducers
ForceSeatMI_Status.h, ForceSeatMI_Status.cs – structuren voor de huidige statusgegevens van het bewegingsplatform
Unity/*.cs – Unity 3D C# API
Plugins/UnrealEngine – speciale Unreal Engine plug-in met helper-klasse voor de extractie van voertuig- en vliegtuigtelemetrie
Examples – voorbeelden

ForceSeatMI maakt gebruik van een DLL die wordt geïnstalleerd als onderdeel van de ForceSeatPM-software. Zorg ervoor dat je ForceSeatPM op je computer hebt geïnstalleerd.

Vereisten

De volgende talen en frameworks worden standaard ondersteund: C, C++, C#, Unity 3D(C#), Unreal Engine (C++)
De native API-dll is gecompileerd met Visual Studio 2015 – er wordt gebruikgemaakt van statische koppeling met MSVC.
Unity 3D-voorbeelden vereisen Unity 5.x of nieuwer
Unreal Engine-voorbeelden vereisen Unreal Engine 4.14 of nieuwer
C#-voorbeelden vereisen minimaal Visual Studio 2013 Express voor Windows Desktop en .NET Framework 4.0.
C/C++-voorbeelden vereisen minimaal Visual Studio 2013 Express voor Windows Desktop.
Het ondersteunt alleen Windows PC

Bedrijfsmodi

ForceSeatMI werkt in een van de hieronder beschreven modi. Voor nieuwe gebruikers wordt aangeraden om te beginnen met Logical Table Position, omdat dit het eenvoudigste voorbeeld is en werkt met het ingebouwde profiel SDK – Positioning.

Modus	Beschrijving	Applicaties	Aanbevolen profiel
Telemetriegegevens	In deze modus stuurt de SIM informatie over de voertuigpositie, g-krachten en versnellingen in het voertuigcoördinatensysteem rechtstreeks naar ForceSeatPM. De volledige transformatie van krachten naar bewegingen van het bovenframe gebeurt binnen de scripting-engine van ForceSeatPM. Hierdoor kun je eenvoudig mapping- en filterparameters wijzigen zonder dat er iets in de SIM hoeft te worden aangepast.	Games en voertuigfysica-simulaties	SDK – Vehicle Telemetry SDK – Plane Telemetry
Logische tafelpositie	In deze modus stuurt de SIM de positie van het bovenframe (yaw, pitch, roll, heave, sway en surge) in abstracte eenheden (percentages van maximale rotatie/translatie). Hiermee krijgt de SIM volledige controle over de positie van het bovenframe, maar het is aan de SIM om de juiste hoeken en offsets te berekenen.	Voor applicaties die meer controle willen over de framepositie	SDK – Positioning
Nauwkeurige tafelpositie	Deze module gebruikt de door de SIM geleverde transformatiematrix van het bovenframe en berekent de posities van alle armen/actuatoren in werkelijke eenheden.	Applicaties voor het testen van apparatuur	SDK – Positioning

Implementatiedetails

structSize is een verplicht veld dat ingevuld MOET worden. Het wordt gebruikt om de achterwaartse/voorwaartse compatibiliteit tussen de DLL en de SIM te beheren.

telemetry.structSize = sizeof(ForceSeatMI_Telemetry);

mask geeft aan welke andere velden zijn ingesteld. Als de SIM bijvoorbeeld roll levert in de FSMI_TopTablePositionLogical-structuur, dan moet het mask-veld de FSMI_POS_BIT_POSITION-bit bevatten. Het is vereist om altijd het state-veld op te nemen in het masker (FSMI_POS_BIT_STATE of FSMI_TEL_BIT_STATE).

#define FSMI_POS_BIT_STATE ...
#define FSMI_POS_BIT_POSITION ...
#define FSMI_POS_BIT_MATRIX ...
#define FSMI_POS_BIT_MAX_SPEED ...
#define FSMI_POS_BIT_TRIGGERS ...
#define FSMI_POS_BIT_AUX ...
 
#define FSMI_TEL_BIT_STATE ...
#define FSMI_TEL_BIT_RPM ...
#define FSMI_TEL_BIT_SPEED ...
 
#define FSMI_TEL_BIT_YAW_PITCH_ROLL ...
#define FSMI_TEL_BIT_YAW_PITCH_ROLL_ACCELERATION ...
#define FSMI_TEL_BIT_YAW_PITCH_ROLL_SPEED ...
#define FSMI_TEL_BIT_SWAY_HEAVE_SURGE_ACCELERATION ...
#define FSMI_TEL_BIT_SWAY_HEAVE_SURGE_SPEED ...
 
#define FSMI_TEL_BIT_PEDALS_POSITION ...
#define FSMI_TEL_BIT_GEAR_NUMBER ...
#define FSMI_TEL_BIT_GROUND_TYPE ...
#define FSMI_TEL_BIT_COLLISION ...
 
#define FSMI_TEL_BIT_GLOBAL_POSITION ...
#define FSMI_TEL_BIT_TIME ...
#define FSMI_TEL_BIT_TRIGGERS ...
 
#define FSMI_TEL_BIT_MAX_RPM ...
#define FSMI_TEL_BIT_FLAGS ...
#define FSMI_TEL_BIT_AUX ...

Als ForceSeatMI in de SIM wordt gebruikt, moet de SIM ten minste één keer ForceSeatMI_BeginMotionControl aanroepen, anders blijft de pauze-status constant aanwezig. Na de eerste aanroep kun je kiezen hoe je de pauze afhandelt. Eén optie is om ForceSeatMI_EndMotionControl aan te roepen en een andere optie is om de state-bit in te stellen. Onze aanbeveling is als volgt:

Wanneer de SIM de runtime-modus activeert (het gaat telemetriegegevens verzenden), roept het ForceSeatMI_BeginMotionControl aan
Wanneer de SIM de runtime-modus verlaat (het gaat een tijdje geen telemetriegegevens verzenden), roept het ForceSeatMI_EndMotionControl aan
Wanneer er tijdens runtime een korte pauze plaatsvindt (bijv. de gebruiker drukt op pauze op een toetsenbord), moet de SIM het state-veld gebruiken

Met andere woorden, het wordt aanbevolen om ForceSeatMI_BeginMotionControl/ForceSeatMI_EndMotionControl te gebruiken voor de overgangen tussen runtime en het hoofdmenu, en state voor korte pauze-gebeurtenissen.

state-velden bestaan uit 8 bits, maar in de huidige versie wordt alleen de eerste bit gebruikt.

BIT nr. 0 — 1 (FSMI_STATE_PAUSE) betekent dat de runtime-modus in de SIM is gepauzeerd, 0 (FSMI_STATE_NO_PAUSE) betekent dat de runtime-modus in de SIM actief is.

Vergeet niet om FSMI_POS_BIT_STATE of FSMI_TEL_BIT_STATE aan het masker toe te voegen als het state-veld wordt ingesteld. Zorg ervoor dat je state ten minste één keer instelt om het bewegingsplatform te hervatten nadat ForceSeatMI_BeginMotionControl is aangeroepen.

Voorbeelden

De volgende voorbeelden worden samen met de SDK geleverd. Zorg ervoor dat je voor elk voorbeeld het juiste profiel gebruikt.

Voorbeeld	Beschrijving	Vereist profiel
TableLogPos_CPP TableLogPos_CS TableLogPos_Unity TableLogPos_Unreal	Laat zien hoe je de positie van het bovenframe kunt regelen door roll, pitch, yaw, heave, sway en surge op te geven in een percentage van de maximale bewegingen. Dit kan worden gebruikt om alle soorten bewegingsplatforms aan te sturen.	SDK – Positioning
TablePhyPos_CPP TablePhyPos_CS TablePhyPos_Unity TablePhyPos_Unreal	Laat zien hoe je een nauwkeurige positie van het bovenframe opgeeft door roll, pitch, yaw, heave, sway en surge in werkelijke eenheden op te geven. Dit werkt alleen met 3DoF- en 6DoF-machines.	SDK – Positioning
TableMatrixPos_CPP TableMatrixPos_CS	Laat zien hoe je een nauwkeurige positie van het bovenframe opgeeft door een transformatiematrix te verstrekken. Dit wordt alleen aanbevolen voor 6DoF-machines.	SDK – Positioning
Telemetry_Veh_Unity Telemetry_Veh_Unreal	Laat zien hoe je voertuigtelemetriegegevens van de SIM naar ForceSeatPM stuurt.	SDK – Vehicle Telemetry
Telemetry_Fly_Unity Telemetry_Fly_Unreal	Laat zien hoe je vliegtuigtelemetriegegevens van de SIM naar ForceSeatPM stuurt.	SDK – Plane Telemetry

Tot slot

Wanneer het platform niet beweegt of het systeem in de pauzestand staat, doe dan het volgende:
- Controleer of het juiste profiel actief is in ForceSeatPM
- Controleer of het juiste profiel is geïmporteerd in ForceSeatPM (verschillende bedrijfsmodi vereisen verschillende profielen)
- Controleer de ForceSeatMI-diagnose om te zien of ForceSeatPM gegevens van de SIM ontvangt.
- Controleer of de gepauzeerd-indicator aan of uit staat
- Vergeet niet om het mask-veld te configureren
- Vergeet niet om de juiste state-waarde in te stellen om de pauzemodus te verlaten.
ForceSeatMI32.dll/ForceSeatMI64.dll zijn ontworpen voor hoge prestaties, dus er is geen logging beschikbaar en de DLL voert slechts de minimaal noodzakelijke gegevensconsistentiecontroles uit.