Shark Planner: waypoint entry into Ka-50 ABRIS and PVI-800 from F10

[okopanja]

Introduction

SharkPlanner has started a MOD for entry of waypoints into ABRIS and PVI-800 of DCS Ka-50 attack helicopter. The mod enables entry of:

• waypoints into ABRIS/PVI-800/NADIR
• fix points (used for INU/INS corrections)
• target points (used for autopilot ingress, SHKVAL slewing and DL operations)
• review of elevation profile along route

Meanwhile SharkPlanner supports additional modules...

FAQ

How does it work?

SharkPlanner runs as a LUA script hook and is able to utilize DCS's native UI in order to deliver minimalistic UI without requiring external application.

Does it break integrity check?

No, SharkPlanner is not deployed in your game installation folder.

Do I need binary/exe?

No, SharkPlanner runs within the DCS, and as such does not require external tools to run.

Which DCS versions are supported?

Minimal requirement is 2.8 either stable or openbeta.

Which airframes are supported?

• BlackShark 3: Ka-50 version 2022
• BlackShark 3: Ka-50 version 2011
• BlackShark 2: Ka-50
• Combined Arms (only information gathering)
• Gazelle: SA-342L
• Gazelle: SA-342M
• Gazelle: SA-342Minigun
• F-16C
• JF-17 Thunder

How do I report bugs?

Open the issues, read existing open issues to quickly figure out if your issue is already reported, and if you find none create new issue. Please try to be precise and provide the steps for reproduction and if needed:

• screenshots if available
• links to video if available
• mission file if available (needs to be renamed into zip, I recommend my_mission.miz.zip)
• dcs.log, located at %USERPROFILE%\Saved Games\DCS.openbeta\Logs or %USERPROFILE%\Saved Games\DCS\Logs

If you do not have github account you can post error report here and I will create the issue on github page.

Installation instructions

1. Download the latest release. The needed package is named like this: SharkPlanner-VERSION.zip
2. Unpack the content of the zip file into %USERPROFILE%\Saved Games\DCS.openbeta\Scripts or %USERPROFILE%\Saved Games\DCS\Scripts depending on version of the DCS you are using.
3. Start or restart DCS

Usage instructions

1. Start DCS
2. Hop into your Black Shark
3. Switch to F10 mode
4. Hit: CTRL+SHIFT+SPACE
5. You should see a crosshair in the middle of screen. Above crosshair the following buttons are located: Hide, Add, Reset, Transfer as well as label showing current and maximal number of waypoints.
6. Use your mouse to zoom and pan to your point of interest, and use Add button to select your waypoints.
7. Once you add at least one waypoint, you can click on Transfer button and SharkPlanner will start entering waypoints/fixpoints/targetpoints into ABRIS and PVI-800. It is recommended to do this on ground for maximal accuracy.
8. If you would like to create a new route, hit Reset and go to step 5.
9. To hide SharkPlanner hit again: CTRL+SHIFT+SPACE

Removal instructions

To remove SharkPlanner:

1. Delete file %USERPROFILE%\Saved Games\DCS.openbeta\Scripts\Hooks\SharkPlanner.lua or %USERPROFILE%\Saved Games\DCS\Scripts\Hooks\SharkPlanner.lua depending on version of the DCS you are using.
2. Delete folder %USERPROFILE%\Saved Games\DCS.openbeta\Scripts\SharkPlanner or %USERPROFILE%\Saved Games\DCS\Scripts\SharkPlanner depending on version of the DCS you are using.
3. Restart DCS if it was running

Kudos

• TheWay is a very cool project which enables entry of waypoints for a rather large number of DCS airframes. My initial motivation was to provide the ABRIS support as code contribution to TheWay, but ABRIS proved to be very challanging to implement within existing framework since coordinates entry can be done only non-numerically through dials. This limitation has resulted in large changes that could not be easily harmonized and tested with existing code base. Please note that TheWay remains to be the most comprehensive software for waypoint entry in DCS and is highly recommended to use for all other supported aircrafts. You can use both SharkPlanner and TheWay as long as you remember not to invoke transfer of waypoints at the same time!
• DCS Scratchpad provided the idea how to inject the UI and trigger it with a keyboard shortcut.

Edited October 22, 2023 by okopanja
update

[Akiazusa]

Great work man.

This is going to save a lot of time for me to input waypoints (and also save my neck)

(now I know why you are looking for some export scripts earlier this month)

[okopanja]

25 minutes ago, Akiazusa said:

(now I know why you are looking for some export scripts earlier this month)

I initially provided extension to TheWay, but depending on external EXE meant we would need to create EXE from java (cumbersome) and that user would need to download it and trust it. So I started looking into another way to implement it, initally in C#, but then I started looking into dxgui subfolder and into FC3 clickable cockpit mod.

Actually, at that point I was trying to create a true tech/service MOD, only 2 critical functions do not exist there. I gather they exist in C++ SDK, but I do not have access, so at the end I opted to employ same technique the DCS Scratchpad did. IMHO: using hooks is not ideal, but it works good enough and it does not require users to edit Export.lua file. Furthermore this will allow way closer interaction.

Anyway feedback and suggestions are welcome.

[Devrim]

Wow. Impressive! Not the mod, your voice! 

Thanks for the mod by the way. Probably I'll use the traditional way for the realism but I must say really good work, man. I haven't seen such a unique work for a long time on the DCS.
Bravo. 

Edited February 28, 2023 by Devrim

[okopanja]

24 minutes ago, Devrim said:

Wow. Impressive! Not the mod, your voice! 

Thanks for the mod by the way. Probably I'll use the traditional way for the realism but I must say really good work, man. I haven't seen such a unique work for a long time on the DCS.
Bravo. 

 

Thanks, but voice is the consequence of a combination of hard case of cold and the need to be silent not to wake kids up.

It took 2 very intensive weeks last year to figure out how to enter coordinates into ABRIS with only dials and zoom. I am still not sure if it works for all people correctly, since it is very timing sensitive. It appears that it needs some delay to settle before a proper input can be made. For some reason ABRIS will place coordinate system at 0,0 of present map, and few ms later move it to where the aircraft is. On the other side if I let it execute slower it results in corrupted entry so I am kind of disappointed I could not let it play at speed comprehensible by human.  PVI-800 was easier so I did slow it down to some degree, so it can be seen what it does.

[okopanja]

v0.0.6 release:

• PVI-800: Implemented target points
• Improved UI feedback

Edited March 2, 2023 by okopanja

[okopanja]

v0.1.0 release:

• Refactored module detection and loading
• Implement fix point entry
• Resolved bug preventing the hiding through shortcut

Additional notes:

• Fix points enable the corrections of the INS alignment.
• Target points when selected in PVI-800 can be use for 3 purposes:
  • autopilot ingress
  • slewing the SHKVAL onto target point (select target point, then hit O, and SHKVAL will hold the target point!).
  • creating of DL targets, which results in ABRIS entry and possibility to send the target to the wingmen
• Sadly, I had to replace the two state checkbox with improvised 3 state button. I do not have artistic affinity, so if anyone thinks he can provide royalty free artwork (ideally CC), please contact me via private message.

Edited March 8, 2023 by okopanja
Attached screenshot

[Hobel]

sorry if I missed it.
But is it possible to create a plan in the SP and save it?
and the next day I can call up this plan again directly?

 

[okopanja]

6 hours ago, Hobel said:

But is it possible to create a plan in the SP and save it?

This is not implemented yet, but it is certainly possible. There may be more than one approach to do this. E.g. implicit file/path generation (e.g. derived from mission file path) or by reusing ED's own Open/Save dialogs (need to try this first). I prefer to avoid any textual entry outside of F10 view (this can interfere with MP chat.

6 hours ago, Hobel said:

and the next day I can call up this plan again directly?

Yes this would be possible. At the moment I am still considering if the tool should display the textual and/or graphical representation of entered waypoints.

I intend to slow down a bit due to personal obligations, and wait for more feedback on bugs. I am worried that no one reported the bugs, since software with no bugs has not be written yet.

More specifically, the waypoint entry into device is based on delays expressed in milliseconds. In theory it should work the same on machine with 15 FPS and >100 FPS. In reality the population of mod users is rather small, so I can not be sure if this works for everyone. E.g. does it work for VR users (TrackIR user here)?

I have some questions myself:

Are your questions related to the play or more to the testing? (e.g. fix points and nav points could be interesting from the point of INU testing).

Do you have any test specific needs?

[Hobel]

vor 29 Minuten schrieb okopanja:

This is not implemented yet, but it is certainly possible. There may be more than one approach to do this. E.g. implicit file/path generation (e.g. derived from mission file path) or by reusing ED's own Open/Save dialogs (need to try this first). I prefer to avoid any textual entry outside of F10 view (this can interfere with MP chat.

Yes this would be possible. At the moment I am still considering if the tool should display the textual and/or graphical representation of entered waypoints.

I intend to slow down a bit due to personal obligations, and wait for more feedback on bugs. I am worried that no one reported the bugs, since software with no bugs has not be written yet.

More specifically, the waypoint entry into device is based on delays expressed in milliseconds. In theory it should work the same on machine with 15 FPS and >100 FPS. In reality the population of mod users is rather small, so I can not be sure if this works for everyone. E.g. does it work for VR users (TrackIR user here)?

I have some questions myself:

Are your questions related to the play or more to the testing? (e.g. fix points and nav points could be interesting from the point of INU testing).

Do you have any test specific needs?

So theoretically it would also be possible to share the saved plan with your friends? All in all, this sounds great, I am curious and look forward to what is still to come! 

 

 

Thx!

[okopanja]

34 minutes ago, Hobel said:

So theoretically it would also be possible to share the saved plan with your friends? All in all, this sounds great, I am curious and look forward to what is still to come! 

Yes, it would be possible, but with a caveat: they would have a very limited way to review what you have entered. I do not intend to go to the Combat Flite level.

I will consider which format to use to save, most likely JSON, since the encoder/decoder is already there, although YAML or a simple text files would be more readable for non-programmers.

[Wostg]

Hi I just wanted to say thanks very much for making this, Its opened up parts of the blackshark I would never have gotten to otherwise. In time it's going to assist me to learn these functions the long way.

[okopanja]

Short update: working on Combined Arms support as a source of intel data... Once completed you will be able to activate planner from within JTAC seat for target point designation and then switch to black shark for actual transfer.

Edited March 13, 2023 by okopanja
clarification

[okopanja]

v0.1.2 release:

What's Changed

• Combined Arms Support: intelligence data can be captured in combined arms modes and transferred once you switch to Black Shark.
• Prevented overlapping transfers

Special notes

• Combined Arms: although you can capture way more points then BS supports. If the number is larger, SharkPlanner will prune points to supported number and keep only the first 6/10/10 way/nav/target points.
• With 0.1.0 version the support for BS2 and BS3 2011 was broken during code refactoring. This was fixed in pre-release 0.1.1

[okopanja]

Soon...

Edited April 22, 2023 by okopanja

[okopanja]

v1.0.0 release:

What's Changed

• UI improvements
  • Buttons got real skins themed according to Black Shark
  • Waypoint counter is now button and when clicked shows waypoint list
  • Reworked status window
  • Added Waypoint list window
  • Implemented Load & Save function
  • Removal of arbitrary points is possible
• Internal changes
  • UI is now object oriented reacting to events
  • Majority of log entries are moved to Logs\SharkPlanner.log
  • Improved stability of ABRIS entry (this needs user feedback!)
  • SharkPlanner has doubled in size from ~40KB to 83.1 KB

Edited April 29, 2023 by okopanja

[Kamicosmos]

Very Awesome Tool!  I had just found The Way, and was figuring out how to make the routes when Sharkplanner was recommended to me on the Rotorheads discord.  Set it up and awesome!  It's very easy to use, and it so nice finally having waypoints and routes in the ABRIS and being able to let the autopilot do some work for a change!

 

[okopanja]

10 hours ago, Kamicosmos said:

Very Awesome Tool!  I had just found The Way, and was figuring out how to make the routes when Sharkplanner was recommended to me on the Rotorheads discord.  Set it up and awesome!  It's very easy to use, and it so nice finally having waypoints and routes in the ABRIS and being able to let the autopilot do some work for a change!

 

I am glad you liked it. At the moment the focus is on Black Shark, but I will soon start learning Gazelle. The feature list for ABRIS is still not complete, e.g. missing are:

1. targets (except for those coming from Rubikon)
2. waypoint altitudes
3. waypoint names (I might be able to derive this from nearest toponyms. So far it looks like towns are easy pick, but other types of toponyms like mountain peaks and rivers are not that easily accessible.
4. wind information

Since the entry is done through dials, it is very difficult to have 100% stable and reliable entry, so I will have to yet to asses which of these are actually feasible to implement. E.g. using the dial for menu navigation and waypoint name entry, looks very finicky and non deterministic when entered properly.

I think adding targets into ABRIS might be feasible since it is pretty much the same input method as for waypoints.

[okopanja]

Shark Planner v1.0.1:

What's Changed

• Improved position table:
  • Geographical coordinates are showed in single cell in 2 lines
  • Altitude cell displays delta altitude and altitude
  • Introduced distance between waypoints in 2 lines: delta between waypoints / cumulative distance including waypoint
• Logging improvements
  • Fixed logging levels
  • Logging is removed from dcs.log as much as possible
• Developer only feature
  • Implement experimental button
  • Button executes experiment.lua which is reloaded on each invocation. Context is provided to store intermediate states.

Known issues

1. https://github.com/okopanja/SharkPlanner/issues/40

Direct download

Edited May 4, 2023 by okopanja
Updated text and links

[Blockbuster]

The Shark Planner is absolutely fantastic but unfortunately I found that it doesn't work on the Normandy map see the screenshot. The coordinates on the map are North and West, but in Planner North and East.

[okopanja]

1 hour ago, Blockbuster said:

The Shark Planner is absolutely fantastic but unfortunately I found that it doesn't work on the Normandy map see the screenshot. The coordinates on the map are North and West, but in Planner North and East.

Thank you for reporting. This should be fairly easy to fix. Likely it does not work for Southern hemisphere as well. I have created a bug report here: https://github.com/okopanja/SharkPlanner/issues/40 in case you use github.com.

I will fix this in the next release.

Btw: I entered the coordinates once on Caucasus, only later to enter same coordinates in Syria. It looked fine, which probably means that maps share the same coordinate system with center located on Crimea. Later edit: just found out the X/Z coordinate systems are separate per each maps. This means I will have to actually use the Longitude/Latitude and derive X/Z from them.

Mental note: looks like it's about the time to start thinking on the unit test concept and quality gates implemented in github actions.

Edited May 4, 2023 by okopanja
Updated facts.

[Hobel]

Am 3.5.2023 um 19:19 schrieb okopanja:

Shark Planner v1.0.1:

What's Changed

• Improved position table:
  • Geographical coordinates are showed in single cell in 2 lines
  • Altitude cell displays delta altitude and altitude
  • Introduced distance between waypoints in 2 lines: delta between waypoints / cumulative distance including waypoint
• Logging improvements
  • Fixed logging levels
  • Logging is removed from dcs.log as much as possible
• Developer only feature
  • Implement experimental button
  • Button executes experiment.lua which is reloaded on each invocation. Context is provided to store intermediate states.

Direct download

 

I have not been able to test it, but can the Planner also enter the Altitude into the PVI-800 through a backdoor, just like the ME does?

[okopanja]

2 hours ago, Hobel said:

I have not been able to test it, but can the Planner also enter the Altitude into the PVI-800 through a backdoor, just like the ME does?

No, it can not. This actually makes SHKVAL slewing based on navigation target point unreliable. If the altitude is e.g. 500m then the Shkval will be slewed to 0m. This results that view will show area which is much nearer than the actual area of interest.

See here for more details. I kind of did rise issue about this but not officially.

 

Edited May 4, 2023 by okopanja
typos

[okopanja]

1 hour ago, Blockbuster said:

The Shark Planner is absolutely fantastic but unfortunately I found that it doesn't work on the Normandy map see the screenshot. The coordinates on the map are North and West, but in Planner North and East.

I think I found the solution for the problem, lat/long coordinate remain compatible irrespective of the map being used. However, this uncovered another issue: if you enter coordinates on one MAP and move to another, the SharkPlanner will enter coordinates from prior map incorrectly. I will have to make further changes to the code so X/Z get recalculated based on  when user changes map.

 

[okopanja]

Shark Planner v1.0.2 - this upgrade is mandatory for any map having coordinates in Western/Southern hemispere

What's Changed

• Fixed problem with coordinates display
• Correct conversion of geographical coordinates in western/southern hemisphere
  • Fixed issue with wrong coordinate being entered in Western/Southern hemispheres into PVI-800.

Known issues

1. When switching maps the coordinates of map's local coordinate systems are not recalculated https://github.com/okopanja/SharkPlanner/issues/44

Edited May 5, 2023 by okopanja