SE - SAMv2 Configuration guide

Configuration guide for using SAMv2 script for Space Engineers.

What is this?

SAMv2 - a script for Space Engineers

http://steamcommunity.com/sharedfiles/filedetails/?id=1653875433

• Have your ship autonomously and automatically fly between any multiple Connectors in the Star System, without having to worry about recording waypoints.
  
• Turn your ships into autonomous navigation vessels. Without a need for a cockpit, just tell it where you want to go, and it goes, with or without you as a passenger.
  
• Automate cargo runs with ease. In the plannet and in Between planets.
  
• Worried about mountains and collisions? Worried about your Remote Controller getting stuck? Don't worry anymore.

Installation

Ships Require:

• Remote Controller - Add one anywhere in the ship.
  
• Camera - Ideally 3, one facing UP, FRONT & DOWN. Avoid that they are obstructed by other blocks in the ship.
  
• Programmable block - Add one to your ship, add this script to it.
  
• Connector - At least one.

Ships can Additionally have:

• LCD Panel - At leat one. Add a wide second one for having a Syslog.
  
• Antenna - Important as this allows the ship to learn about Connectors in other grids.
  
• Cockpit - Used for the LCD Panels.
  
• Batteries - If you want to make sure batteries are charged before navigating to the next dock.
  
• Cargo Containers - If you want to make sure Cargo Containers are loaded or unloaded before navigating to the next dock.

Stations Require:

• Programmable block - Add one to the grid.
  
• Connector - At least one.
  
• Antenna - Important as this allows the Station to advertise its connectors to other grids. However this block does not need to be tagged. Make sure it has enable broadcast set.

Tagging

SAMv2 supports two methods for tagging a block. SAM will first check Custom Data, and then the Block Name. It does not need to use both at the same time. Either one will work.
Only blocks on the same construct will be considered (connected by pistons or rotors, but not connectors).

Block name

This allows tagging the block using the block name. Example for an LCD Pannel:

Wide LCD Pannel [SAM LOG]

Custom Data

This allows the blocks to be tagged without polluting the block name, good for antennas. Example, add the following to the Custom Data of an LCD pannel:

SAM.
SAM.Log

Notes for the use of Custom Data with other scripts
SAMv2 scans every line in Custom Data and checks if there is a SAM.something. If there is, it uses it. It leaves everything else untouched.

Usage

Tag all required blocks above with SAM. More specifically:
For Station Programmable blocks

• add the tag "advertise". Example: [SAM ADVERTISE]
  
• override the grid name (no spaces). Example: [SAM ADVERTISE Name=NewGridName]

For Station Connectors:

• override the block name (no spaces). Example: [SAM Name=NewConnectorName]

For Ships Wide LCD Pannels:

• add the tag "log" for seeing the Syslog. Example: [SAM LOG]

Continuous modes

Additionally, For Ships Programmable blocks use tag LIST or LOOP:

• [SAM LIST] - Hops dock to dock in the list till the end.
  
• [SAM LOOP] - Hops dock to dock in the list till the end then starts over.
  
• [SAM] - Navigation needs to be manually started for every dock in the list.
  
• [SAM LIST Wait=20] - Also works for LOOP, overrides the 10 second wait times between docks.

Charge and Cargo

IMPORTANT: SAMv2 *does not* by itself load, unload or charge anything. It needs an external system to do it. SAMv2 only monitors for full, empty, charged or uncharged blocks.

While in LIST or LOOP modes, it is possible to tell a dock to wait to cargo to be Loaded or Unloaded or Batteries to be Charged before moving to the next dock. This can be done with the "select" button in the NAV screen.

The respective Cargo Containers and or Batteries need to be tagged with [SAM].

Hydrogen tanks by default are "Charged", all they need is to have the [SAM] tag too. If there is a mix of Hydrogen tanks and Batteries tagged, then "Charge" will wait for all the batteries to be charged and all the tanks to be filled.

If you want to haul hydrogen, you can tag the Hydrogen tanks with [SAM CARGO] and it will be considered cargo instead.

It is also possible to define what Empty and Full means for Batteries, Tanks and Cargo Containers. The following Tag means to consider empty whenever the charge or fill is bellow 10%, and to consider full whenever the charge or fill is above 90% of the battery max charge, Cargo max volume or tank max volume:

[SAM Empty=10 Full=90]

Also for Batteries and Tanks, use the following tag to force the batteries to recharge and tanks to stockpile. Note that Hydrogen Tanks with the CARGO tag will stockpile automatically;

[SAM FORCE]

Ship commands

Issue the following commands to the Programmable Block:

• PREV - Previous item.
  
• NEXT - Next item.
  
• SELECT
  
  • Select the existing item (for Configuration screen).
    
  • Changes wait mode (Charge,Load,Unload) (for Navigation screen).
• SCREEN - Changes back and forth between Navigation and Configuration screens.

• ADD ORBIT - Adds the GPS position in Orbit right above the ship.
  
• ADD <GPS> - Adds the GPS position as an entry. Uses the GPS name as the entry name.
  
• ADD [STANCE] <Name> - Adds the present ship position or connected dock as an entry.
  • If ship is connected to a dock it will add the new dock use <Name> to override the dock name;
    
  • <Name> is optional - adds a name;
    
  • STANCE is optional - when adding the current position it also adds the current orientation (ignored when adding a dock);
• REMOVE - Removes entries added with the ADD command and old docks that have stopped being advertised (have a ? before them)

• START - Starts navigation to the selected dock in the Navigation screen.
  
• START PREV - Selects the previous dock in the Navigation screen and Starts navigation.
  
• START NEXT - Selects the next dock in the Navigation screen and Starts navigation.
  
• START (GPS Coordinate) - Starts navigation to the GPS coordinate copied from the GPS screen.
  
• STOP - Immediately stops navigation.
  
• TOGGLE - Toggle between START/STOP.
  
• GO (Connector Name) - Will immediately start navigating to the Connector Name. The connector name must be the one given with the TAG Name.

• CLEARSTORAGE - Clears storage, requires the program block to recompile.
  
• CLEARLOG - Clears the Log.

Additional details

Text Pannels

Use the following TAGs:

• [SAM] - Shows the selected screen (either NAV or CONF).
  
• [SAM LOG] - Shows the log.
  
• [SAM NAV] - Shows the NAV screen.
  
• [SAM CONF] - Shows the configuration screen.
  
• [SAM STAT] - A two line status useful for corner screens.
  
• [SAM OVR] - Allows you to override the font size and style.

Thrusters

SAMv2 can be told to ignore thrusters:

[SAM IGNORE]

Programmable Block

Use the following attributes to override specific values:

• [SAM Name:NewName] - Overrides the grid name.
  
• [SAM MaxSpeed:95] - Maximum speed used in NAVIGATING and CONVERGING modes.
  
• [SAM ConvergingSpeed:50] - Converging speed.
  
• [SAM DockingSpeed:2.5] - Speed during the docking/undocking procedure (before/after connector).
  
• [SAM TaxiingSpeed:10] - Speed during taxiing. Before docking, during path following.
  
• [SAM ApproachingSpeed:50] - Approaching speed.
  
• [SAM TaxiingPanelDistance:10] - When using Path-Docking, the distance from the panel.
  
• [SAM TaxiingDistance:10] - How close will the ship get before starting the docking procedure.
  
• [SAM DockDistance:5] - How close to the dock before starting the docking procedure.
  
• [SAM UndockDistance:10] - How far a distance to take after undocking before starting navigation.
  
• [SAM ApproachDistance:500] - Distance from the target at which Approaching navigation mode starts.
  
• [SAM NODAMPENERS] - SAMv2 disables dampeners after docking in order to avoid thrusters from firing while docked (happens when docked to ships). This can be disabled with PB Tag NODAMPENERS;
  
• [SAM IGNOREGRAVITY] - The ship will ignore gravity for alligning. This is usefull for rocket like ships that always face one direction regardless of gravity.

Note that during navigation the script will go through these modes:
UNDOCKING -> [TAXIING] -> [ NAVIGATING | CONVERGING ] -> APPROACHING-> [TAXIING] -> DOCKING

• NAVIGATING -> Used when obstacles are detected in the path.
  
• CONVERGING -> Used when no obstacles are detected in the path.
  
• TAXIING-> Only during Path docking.

Connectors

Some modded connectors have their local space reversed from the vanilla connectors. For these use the TAG REV:

• [SAM REV] - Reverses modded copnnectors;

If you have a ship with many connectors where you use some for other ships to dock, you can define a connector that the main ship will always use for docking.

• [SAM MAIN] - Ship will always dock with this connector. Will not advertise this connector if the ship is also an advertiser.

Cockpits

Use the following TAGs:

• [SAM PANEL0: ] - Shows the default screen in Panel0.
  
• [SAM PANEL0: PANEL2:LOG] - Shows the default screen in Panel0 and the LOG in Panel2.
  
• [SAM PANEL0: PANEL2:LOG OVR] - Same as above and allows Overriding text format like in text panels.
  
• [SAM PANEL1:CONF ] - Shows the CONF screen in Panel1.

Timer Notifications

Notifications can be sent to timer blocks when certain actions are accomplished. Only timers in the same construct are triggered. Tag your timers with:

• [SAM DOCKED] - Starts the timer when the ship docks.
  
• [SAM UNDOCKED] - Starts the timer when the ship undocks.
  
• [SAM NAVIGATED] - Starts the timer when the ship finishes navigation (regardless of docking).
  
• [SAM STARTED] - Starts the timer when the ship starts navigation.

Path docking

You can use LCD screens with an attribute named "Name" with the same value as the one your Dock has. The LCDs are sorted by distance to the Dock, and the ship will follow them all the way. This can be used to avoid colisions or when your dock is inside some building. See the video for more details.

Remote commands

It is possible to send commands to configure and run all SAMv2 ship provided they are connected via an antenna. See the video for an example:

More examples

The following command sends the ShipName to ConnectorNameA in GridNameA to charge its batteries and load its cargo, then go to ConnectoB to unload its cargo:

SAMv2 cmd# run
ShipName
{Charge&Load}[GridNameA]ConnectorNameA
{Unload}ConnectorNameB

Same as above except the navigation is not started:

SAMv2 cmd# run conf
ShipName
{Charge&Load}[GridNameA]ConnectorNameA
{Unload}ConnectorNameB

This starts the navigation:

SAMv2 cmd# start
ShipName

Possible commands

• step - adds the configured docks and enables navigation to only go to the next dock;
  
• run - adds the configured docks and enables navigation to go to all the docks till the end of the list, then stop;
  
• loop - adds the configured docks and loop navigates forever;
  
• step conf - only configures the docks and the mode, does not start;
  
• run conf - only configures the docks and the mode, does not start;
  
• loop conf - only configures the docks and the mode, does not start;
  
• start - starts navigation with the existing configuration;
  
• stop - stops navigation;

Possible actions

• Charge
  
• Charge&Load
  
• Charge&Unload
  
• Load
  
• Unload

Possible navigation string formats

• {Action}[GridName]ConnectorName
  
• {Action}ConnectorName
  
• ConnectorName
  
• {Action}GPS:Name:...
  
• GPS:Name:...

Only use the GridName to disambiguate from different bases with same ConnectorName.

Command to multiple ships

Use a Semicolon ";" examples:

Start navigation on ShipName1, ShipName2 and ShipName3:

SAMv2 cmd# start
ShipName1;
ShipName2;
ShipName3

Start looped navigation on ShipName1, ShipName2 and ShipName3. Each one having their own docks.

SAMv2 cmd# loop
ShipName1
ConnectorA
ConnectorB;
ShipName2
ConnectorC
ConnectorD;
ShipName3
ConnectorE
ConnectorF

When something does not work

• Do you own all blocks in the grid? You should.
  
• Does your ship have enough power/hydrogen? It must.
  
• Does your ship have enough Thrust power in every direction? Including UP. It must.
  
• Do your Antennas have enough range to cover each other and are they enabled to broadcast? They should.
  
• Are all your blocks in the same construct? (adjacent to rotors or pistons but not connectors).

Things are still wrong? I suck at coding. Leave a comment with a link to the game file, perhaps I can help.

[TechCoder]

Very good catch! That certainly would be a LIKELY thing to cause an issue!

SAM looks for tagged blocks with 'SAM' in it, but because of the potential for variations, something like '[CasaMatta]' (anything with 'sam' inside [], not looking at capitals) will cause it to trigger (just double-checked the code - it is there....).

So, to fix this for you right away:

// Change the tag used to identify blocks
public static string TAG = "SAM";

Or, change your named blocks to NOT include [...SaM...] things.

I will put it on a list of 'check into', but the code on this search is tricky as we NEED to sometimes find such things...... (actually it is one of the more complex issues in the code - other than the 'rocket science' flying stuff! :)

[Quercus]

Is a new world, a new game, a new save. I had a lot of building nammed [Casamatta] ... i thought the SAM in the name could play a role. I renammed them all. There is no SAM but what needs to be SAM. Still the issue persist. Adding discord

[TechCoder]

Sounds to me like you found your issue -- something in that connected (and probably 'giant') configuration is taking the script a long time to sort through.

If you have used for years:
1. What CHANGED? (you added 'something' recently that "broke the camel's back")
2. (not likely directly related, but a good idea) what VERSION of SAM are you running? I only support _my_ version

If you need other help, GET ON MY DISCORD (links all over the place in these Comments).

[Quercus]

Script TERMINATED because it run more than 50K instructions. However if I detach my spaceport from my industrial base, it works. Any suggestion?

I have use it for years but never encounter this issue

[TechCoder]

This was just covered yesterday on my Discord (where you will get the best, updated chats, etc,)
Join at https://discord.gg/HWWKkHk5H9
Then, go to https://discordapp.com/channels/871428395257458728/886596166807064598/1430755800166694942

[Mainframe]

Can you control the height the ship will hold above the panel?

[TechCoder]

Not letting SAM 'see' is probably the most common SAM issue - and certainly covered in the PINNED messages on my Discord.

I like your PATROL suggestion (actually surprised it hasn't been asked before in the several years I've maintained SAM), though I will say that unless it is in https://discordapp.com/channels/871428395257458728/991793329182363718 (my SAM wants/needs/desires channel), it will most likely be forgotten as I don't play SE much anymore and non-emergency coding for SE projects is really low priority for me (too busy with IRL programming). When I do get time, I look there for any 'todo' stuff.

[AndrewRP]

Well I feel silly now. I had the cameras but forgot the [SAM] tag on this particular drone.That seems to have fixed my issue. But before this fix, I figured how to use the ADD command to create two waypoints above the mountain (One for the approach and one for the departure) that worked well. Appreciate your response -- Thank you!

Oh, a suggestion, perhaps in a future update you could add a PATROL option (like LOOP or LIST) that would run down the list, then back up in reverse order. So A to B to C, then back to B then A.

[TechCoder]

It is a bit to set up SAM, but actually not all that much.....

If you think about it, if it is running into a mountain, probably it can't SEE very well...... - so, what, n SE does the "seeing"? CAMERAS.......

Fix your cameras (make sure to follow the rules in the doc - and check that front camera for sure - and its tags.....)

Get onto my Discord and there's lots of tips and such.

[AndrewRP]

Finally got SAM up and working after a bit of trial and error. First drone works like a charm (after I sorted out my weight/energy issues). 2nd Drone set up the same way but with a different target and promptly ran head first into a mountain. To be fair, the mountain was between the two Connectors and refused to give way to drone. But I can't help but feel that user error is involved.

After scouring the instructions again I have to ask, does SAM not account for obstacles in the way? Do the two connectors need to be LOS and clear of all obstructions? Is there a setting or option I've missed? I do see the option for Path Docking, which may solve my problem, but it seems like avoiding a mountain would be a basic feature?

Thanks for the assistance, and great work on this script.