InSim Relay client information (old)

[Victor]

-----------------------------------
-- InSim Relay usage information --
-----------------------------------

The InSim Relay is a service that can connect to your LFS host via InSim and relay the InSim information sent by your host, to anyone who connects to the InSim Relay. This relayed data can be used by programmers for various things, such as the LFS Spectator (remote viewing of a race) and race-tracking to store race information and statistics.

To have your host connected to the Relay, see this page on LFS World:
http://www.lfsworld.net/?win=hosts&whichTab=insim_relay

The rest of this document is only for programmers who want to know how to connect with the InSim Relay, so they can make use of the available data.
-NEW : you can now also connect various other insim mods via the relay, because you can 'connect' to a host with an admin password. See the bottom of this document for which packets are allowed to send.


Connecting to the InSim Relay
=============================

The network protocol used with the Relay is UDP and it is located at isrelay.liveforspeed.net port 47474

Connecting to the Relay is done with the CCN packet. To connect, make sure bit 0 of the flags is set, which means 'connect to relay'.
The CCN packet is a multifunctional packet. It is used to connect to the Relay, request a list of available hosts and set various options.
Here is the struct of the connection packet:

struct ClientConnection
{
char Id [4]; // CCN + zero (\0)
byte Flags; // Bit flags for options and 'connect' flag
byte Spare; // spare1
byte Spare; // spare2
byte Spare; // spare2
}

Flags in CCN packet:
#define ISR_CONNECT 1 // bit 0 : 'connect' flag. Must be set to connect to Relay
#define ISR_HOSTLIST 2 // bit 1 : if set, you will get a list of hosts returned
#define ISR_NOMCI 4 // bit 2 : if set, you will not receive MCI packets
#define ISR_VERIFY 8 // bit 3 : if set, 'guaranteed delivery' will be on

The CCN packet with bit 0 set _must_ be your first packet, otherwise your packets will be ignored. To acknowledge that the connection was successful, an ACK packet is sent, if you didn't already request a hostlist in your initial CCN packet.
You can additionally send a CCN packet at any time, to toggle NOMCI and/or VERIFY and to request a hostlist even while still being connected to a host.
A note about guaranteed delivery; it works exactly like with normal InSim guaranteed delivery, so if you don't know how it works, please look in the Insim.txt that comes with LFS.

There is one official case where connecting might fail; when the Relay has reached its maximum number of users.
In that case, the Relay will send an ERR packet. The ERR packet also has some other error message purposes.

struct ErrorMessage
{
char Id [4]; // ERR + zero
byte ErrNo; // number of the error
byte Spare; // spare1
byte Spare; // spare2
byte Spare; // spare2
}

ErrNo meanings:
1 - Invalid Spectatorpassword given
2 - Relay has reached maximum number of clients
3 - Non-existent hostname given in HOS packet


Receiving the hostlist
======================

When you have requested a list of hosts with bit 1 of the flags in the CCN packet, you will receive a list of hosts. The result packet(s) is/are identified by the CHL id. Every CHL packet contains a maximum of 8 hosts and their respective information. If there are more than 8 hosts available to select from, you will receive multiple CHL packets. You can determine how many CHL packets you should expect by reading the 'total hosts' word in every CHL packet (this number is the same in every CHL packet). You can determine the amount of hosts listed in a CHL packet, by the length of the packet.

struct ClientgetHostList
{
char Id [4]; // CHL + zero
word NrHosts; // Number of total available hosts
byte Spare; // Spare1
byte Spare; // Spare2
char Host [32]; // Hostname(s) (min: 1 / max 8 hostnames - check the length of this packet)
byte NrRacers; // Number of racers on a host
byte Specpass; // 1 if host requires a spectator password
}

An example of the order things in this packet:
3 hosts listed in this packet:

host1[32].host2[32].host3[32].421110

host1 has 4 racers and requires a specpass
host2 has 2 racers and required a specpass
host3 has 1 racer and does not require a specpass


Select a host to receive InSim data from
========================================

To start receiving InSim packets from a host, you must select the host with a HOS packet:

struct SelectHost
{
char Id [4]; // HOS + zero
char Host [32]; // hostname
char Specpass[24]; // spectator password
char Adminpass[16]; // admin password
}

Note that both the full hostname and ^-stripped/converted hostname can be used.

ex. "^1EXAMPLE^v^7HOST ^11" or "EXAMPLE|HOST 1"

Maintaining a connection to the Relay
=====================================

If the relay has not received any data from a client in 60 seconds, the Relay will close the connection with the client. To prevent this from happening, the client can send ACK packets every 20 seconds, in case nothing else has been sent to the Relay.

struct Acknowledge
{
char Id [4]; // ACK + zero
}

If you need to, you can optionally add 4 null bytes, but it's not required for the relay to recognise the ACK packet.

The same goes for the other way around. The Relay will send ACK packets to your client in case nothing has been sent in 20 seconds. You can make your client assume that the Relay is offline, if you didn't receive anything from the relay during 60 seconds.


Closing a connection (client side)
=========================

When the client closes, it's nice to have it send a 'close' instruction to the Relay:

struct ClientClose
{
char Id [4]; // ISC + zero
}

If you need to, you can optionally add 4 null bytes, but it's not required for the relay to recognise the ISC packet.

Closing a connection (relay side)
=========================

If the relay needs to "close" your connection for whatever reason or if the relay goes offline, it will send a packet to notify that you will need to try to connect again with the CCN packet.

struct ClientTerminate
{
char Id [4]; // CTM + zero
}

Public requests for host information
====================================

A client can request some information from a host by sending the relay one of the following InSim packets:

SST
ISM
VER
GTH
NPL
RES

These packets are regular InSim packets, so for their structs, please see the insim.txt file included with every distribution of S2 or the S2 dedicated host.


Admin-only control packets
==========================

If you have connected to a host with the adminpassword set (in the HOS packet), you are allowed to send some control packets:

VTC
SCH
MST
MTC

These packets are regular InSim packets, so for their structs, please see the insim.txt file included with every distribution of S2 or the S2 dedicated host.

[Victor]

one note - i know the CHL packet struct isn't an official struct (it wouldn't work as it does in c++ or so), but it's been like that from the start, so it's the idea that counts and it does work ;) If you can't get a grasp on it, just ask and I'll try to explain.

[sdether]

Very cool. Can't wait to see what people come up with using this.

It'll probably be a couple of weeks before i have the time to get the new methods into my Lib to let it work seamlessly as a relay client.

[Messiah]

Yay, relay's back! Victor, you rule and Scawen rock :D :
http://www.uo-bab.de/user/jack/yourule.jpg

[Victor]

two updates:

1) in the CCN packet, guaranteed delivery (like with regular insim) can be enabled (for you stats boys :) ).

2) in the HOS packet both full hostnames and ^-stripped/converted hostnames can be used.

See the first post for more details.

[CrazyICE]

Yay, relay's back! Victor, you rule and Scawen rock :D :
http://www.uo-bab.de/user/jack/yourule.jpg
and eric....? :)

thx vic!

[Messiah]

and eric....? :)

thx vic!

He's the artist, he has drawn the picture! d'oh! ;))

[wabz]

Can NCN requests be sent through the relay too please?

p.s. http://www.browseforspeed.net/files/relaypatch.diff.txt is the beginnings of a patch against 0.11b of sdether's insim library which adds connecting/messages through relay functionality. It works, but doesn't do everything it should - throw exceptions on errors etc. Browse For Speed 0.5's LFSLib.dll is built with that patch.

[Becky Rose]

Can the timescale of the 15 relay reconnection attempts be rescaled please?

When there is an outage it seems that if your server ( or in todays case, LFS World ) is not back up and running in a few minutes then the server owners have to re-establish the link again - I seem to have to re-establish the link quite often, and think it would help massively if the 15 reconnect attempts occur over a period of 1 day.

Thank you.

[l1k3z0mg]

edited by Gunn

[Dygear]

I beg of you, make a pit InSim packet for your up coming V patches.

[CLRS530]

Hi, in wich intervall are the MCI packets going to be send?

EDIT: fine intervall is 500ms

[GeForz]

Are the relay packets going to be updated for the new version?

[sdether]

I haven't used the Relay before, but want to include it in the next version of LFSLib.NET. Is it currently up and running for patch X, using the old relay packets or should I be waiting for the relay to catch up to X?

thanks,
sdether

[banshee56]

Any word on when the Relay page will be updated for X and working again?

Victor?

[Victor]

i was working on it before the competitions started. But then I had to get onto the competitions and some other things, so insim relay development got paused. I hope to continue it again later this month. Shouldn't take too long anymore to finish it, though it'll also need a bit of testing to check if it's all ok. It's totally rewritten, so there may be bugs .. hence the need for testing.

[Victor]

Does anyone have, or is working on an application for use with the (new) relay?

I'm currently at the point at which it could do with some more testing and feedback, to see if it works and if it has the functionality it should have for proper use.

If you want to start supporting the relay, you should read the following documentation. It's basically an addition to regular InSim, so it should be reasonably easy to support the relay. You can also send it the regular InSim requests. Connection maintenance is also the same - you should make sure that your application sends something to the relay every 20-30 seconds.

The main differences is that the ISI packet is not used, but instead you select a host with the IR_SEL (InsimRelaySelect) packet.
Also you cannot use _every_ available packet - for example things related to OutGage / OutSim enabling are ignored by the relay.

Docs : (temporary)

// InSimRelay for LFS InSim version 4 (LFS 0.5X and up)
//
// Connect your client to lfs.net:47474 with TCP (vic.lfs.net during testing)
// After you are connected you can request a hostlist, so you can see
// which hosts you can connect to.
// Then you can send a packet to the Relay to select a host. After that
// the Relay will send you all insim data from that host.

// Some hosts require a spectator password in order to be selectable.

// You do not need to specify a spectator password if you use a valid administrator password.

// If you connect with an administrator password, you can send just about every
// regular InSim packet there is available in LFS, just like as if you were connected
// to the host directly. For a full list, see end of document.




// Packet types used for the Relay

#define IRP_HLR 252 // Send : To request a hostlist
#define IRP_HOS 253 // Receive : Hostlist info
#define IRP_SEL 254 // Send : To select a host
#define IRP_ERR 255 // Receive : An error number


// To request a hostlist from the Relay, send this packet :

struct IR_HLR // HostList Request
{
byte Size; // 4
byte Type; // IRP_HLR
byte ReqI;
byte Sp0;
};


// That will return (multiple) packets containing hostnames and some information about them

// The following struct is a subpacket of the IR_HOS packet

struct HInfo // Sub packet for IR_HOS. Contains host information
{
char HName[32]; // Name of the host - can be colourcode stripped

char Track[6]; // Short track name
byte Flags; // Info flags about the host - see NOTE 1) below
byte NumConns; // Number of people on the host
};

// NOTE 1)

#define HOS_SPECPASS 1 // Host requires a spectator password


struct IR_HOS // Hostlist (hosts connected to the Relay)
{
byte Size; // 4 + NumHosts * 40
byte Type; // IRP_HOS
byte ReqI; // As given in IR_HLR
byte NumHosts; // Number of hosts described in this packet

HInfo Info[6]; // Host info for every host in the Relay. 1 to 6 of these in a IR_HOS
};


// To select a host in the Relay, send this packet :

struct IR_SEL // Relay select - packet to select a host, so relay starts sending you data.
{
byte Size; // 68
byte Type; // IRP_SEL
byte ReqI; // If non-zero Relay will send an IS_VER packet
byte Zero; // 0

char HName[32]; // Hostname to receive data from
char Admin[16]; // Admin password (to gain admin access to host)
char Spec[16]; // Spectator password (if host requires it)

};


// If you specify a wrong value, like invalid packet / hostname / adminpass / specpass,
// the Relay returns an error packet :

struct IR_ERR
{
byte Size; // 4
byte Type; // IRP_ERR
byte ReqI; // As given in RL_SEL, otherwise 0
byte ErrNo; // Error number - see NOTE 2) below
};

// NOTE 2) Error numbers :

#define IR_ERR_PACKET 1 // Invalid packet sent by client (wrong structure / length)
#define IR_ERR_PACKET2 2 // Invalid packet sent by client (packet was not allowed to be forwarded to host)
#define IR_ERR_HOSTNAME 3 // Wrong hostname given by client
#define IR_ERR_ADMIN 4 // Wrong admin pass given by client
#define IR_ERR_SPEC 5 // Wrong spec pass given by client


==============================================
Regular insim packets that a relay client can send to host :

For anyone
TINY_VER
TINY_PING
TINY_SCP
TINY_SST
TINY_GTH
TINY_ISM
TINY_NCN
TINY_NPL
TINY_RES
TINY_REO
TINY_RST
TINY_AXI

Admin only
TINY_VTC
ISP_MST
ISP_MSX
ISP_MSL
ISP_MTC
ISP_SCH
ISP_BFN
ISP_BTN

The relay will also accept, but not forward
TINY_NONE // for relay-connection maintenance

feel free to comment or ask for additional features.

[sdether]

Victor,

I'll be implementing Relay support into my library, but I probably won't have anything ready for testing until next week. I'll PM you once I have something I can test with.

[Victor]

np.

But you best just drop a msg here then and I'll contact you. My pm's are turned off :x

[GeForz]

java.net.ConnectException: Connection timed out: connect

I cannot connect to vic.lfs.net; Even with putty the connection just times out.

[Victor]

Are you using tcp? And using port 47474 for sure?

I saw someone else connect, so it should be possible.

[sdether]

vic.lfs.net:47474 works for me. At least I can telnet to it and open the channel. Haven't tried sending packets

[GeForz]

Are you using tcp? And using port 47474 for sure?

I saw someone else connect, so it should be possible.

Sometimes I just hate java :bitehard:

[Victor]

added additional admin-only packet types (packets that the relay will accept from client and relay to host). See the documentation in my post above.

also the test relay is connected to the south city lx month host, so tehre's some activity to test with.

[GeForz]

Just two thoughts for now:
- Use the fourth byte in the IR_ERR packet for the error code
- Allow TINY_NONE replies to TINY_NONE packets received from the relay

Both to make it more consistent with the normal insim.

[Victor]

ok, made those changes

[sdether]

Only now getting around to implementing this. I should probably wait until i queue requests up, but here goes one :)

Can we make IR_HLR use a ReqI for consistency? My API always returns a request id to the caller to use for checking incoming messages and since IR_HLR is a request, it would be nice if it fit into that paradigm


struct IR_HLR // HostList Request
{
byte Size; // 4
byte Type; // IRP_HLR
byte ReqI;
byte Sp1;
};


Also, can we have ReqI instead of Sp0 on IR_ERR. I guess that only partially works since you can send a IR_SEL without an ReqI.

thanks

[chanoman315]

This page is currently not available due to maintenance and will not be available for a couple of days.

Please try again at a later time.

[Victor]

Only now getting around to implementing this. I should probably wait until i queue requests up, but here goes one :)

Can we make IR_HLR use a ReqI for consistency? My API always returns a request id to the caller to use for checking incoming messages and since IR_HLR is a request, it would be nice if it fit into that paradigm


struct IR_HLR // HostList Request
{
byte Size; // 4
byte Type; // IRP_HLR
byte ReqI;
byte Sp1;
};


Also, can we have ReqI instead of Sp0 on IR_ERR. I guess that only partially works since you can send a IR_SEL without an ReqI.

thanks

Alright, that's done. IR_HOS packet(s) will return the ReqI given in IR_HLR and error packets contain the ReqI given in IR_SEL or otherwise 0. Documentation updated with this change.

[sdether]

BTW, I thought i saw that TINY NONE was a valid response now... I was connected to the LX server via the relay and was getting TINY NONE as keep-alive from the server, to which my API automatically response with TINY NONE. This results in an IR_ERR for me.

Also, would it be possible to let me set up a server and have you add it to the relay.. i want to make sure my lib does things properly and the easiest would be if i could syntesize action on the server to watch.

thanks

[Victor]

BTW, I thought i saw that TINY NONE was a valid response now... I was connected to the LX server via the relay and was getting TINY NONE as keep-alive from the server, to which my API automatically response with TINY NONE. This results in an IR_ERR for me.

Also, would it be possible to let me set up a server and have you add it to the relay.. i want to make sure my lib does things properly and the easiest would be if i could syntesize action on the server to watch.

thanks

Right, TINY_NONE is fixed.
To get your host on the test relay, just mail us on our regular email address. Send ip, insim port and adminpass.

EDIT - actually, just go to lfsworld's insim setup page - you have access to it.

[sdether]

actually, just go to lfsworld's insim setup page - you have access to it.

Ok did that.. However that didn't have slots for things like insim port and admin pass. I can email those if you need them.

[Victor]

right, you have now (i mean you can see the entry fields).

[sdether]

Victor,

I'm done with my testing and the relay seems to work as advertised. The only suggestion I would still have is adding ReqI for IR_ERR_PACKET2. Might help people debugging, although it's a design time thing really. Once you know that a packet is invalid, you shouldn't be sending it again or at least not be reacting to it at runtime.

Thanks!

[sdether]

I lied. There still is something after all... Ping and connection maintenance.

I get a TINY/NONE from the relay every ~20 seconds and reply to that with a TINY/NONE. Does that qualify for the connection maintenance?

And should ping's go through? Whether i'm connected to a host via the relay or just the relay, my ping packets seem to get swallowed.

[Victor]

I lied. There still is something after all... Ping and connection maintenance.

I get a TINY/NONE from the relay every ~20 seconds and reply to that with a TINY/NONE. Does that qualify for the connection maintenance?

yeps. That'll keep the connection alive (it's much the same as insim itself really)


And should ping's go through? Whether i'm connected to a host via the relay or just the relay, my ping packets seem to get swallowed.

i just tried it. I connect to relay, then select a host. Then i send a ping packet and the relay relays it to the host which replies back. The relay sends this reply back to client.


And about the IR_ERR_PACKET2 ReqI : i send that now.

[sdether]

i just tried it. I connect to relay, then select a host. Then i send a ping packet and the relay relays it to the host which replies back. The relay sends this reply back to client.



Yeah, my bad. Broken in my lib. My Ping event was looking for a TINY/PING instead of a TINY/REPLY.

Great. I'm feature complete. Thanks!

[BurnOut69]

Is the InSim relay working atm? I can connect and I'm getting keepalive requests but no IR_HOS at all.

EDIT: ok it DOES work, I can see both LX and sdether's hosts

[Victor]

yep, the it's running at the test location.

[Krammeh]

insim relay not enabled atm?

It says that its unavailable... Or is it that I dont have access?

[Victor]

A test relay is running, which is basically done and could go live. The problem is that there aren't any clients I know of that work with it atm, apart from sdether's lib. Which is not to say that would not be reason enough to put it live, but afaik the relay was most used for use with the spectator. And there's no working version of the spectator atm. So what it comes down to is that there's basically no use for the relay at the moment, which is why I'm not in a hurry to put it live.

[Krammeh]

ah right.

I never use a lib for my apps. I was planning on making a few things that use it, to make my life easier.

Any chance you could give me access to it? so i could develop a few things?

I am even tempted to develop a lib for it?

[bdshan]

I have been waiting for the relay to be resurrected. I was going to test if the insim gateway which converts insim v4 to v3 could jump start the use of spectator until an insim v4 version could be created.

sdether's lib could go a long way in part 2, but at least if there was a relay service and the gateway worked as designed people could use the old spectator.

[sdether]

I'll try to package up 0.16b (with Relay support) of my lib today or tomorrow and release it. That way people can do some more testing against the test server before it goes live.

[Victor]

ah right.

I never use a lib for my apps. I was planning on making a few things that use it, to make my life easier.

Any chance you could give me access to it? so i could develop a few things?

I am even tempted to develop a lib for it?

anyone can connect to the test version. Just make your client connect to vic.lfs.net:47474 instead of lfs.net:47474

Additionally you have access to the insim relay setup page at lfsworld (so you can add a host if you'd want)

[Victor]

I have been waiting for the relay to be resurrected. I was going to test if the insim gateway which converts insim v4 to v3 could jump start the use of spectator until an insim v4 version could be created.

sdether's lib could go a long way in part 2, but at least if there was a relay service and the gateway worked as designed people could use the old spectator.

same as for Krammeh - you can test right now. If you need access to the insim relay hosts setup page at lfsworld, let me know.

[Krammeh]

anyone can connect to the test version. Just make your client connect to vic.lfs.net:47474 instead of lfs.net:47474

Additionally you have access to the insim relay setup page at lfsworld (so you can add a host if you'd want)

I have added my host (one of anyway) and the status just sits at connecting. Anything I'm doing wrong?

[Victor]

gah, no, was my fault. I shut the relay down when i was having internet problems a little earlier. It's up again now though.

[bdshan]

Great.

Please grant me access to the insim relay setup page at lfsworld so I can add on of my hosts.

[Victor]

done

[Krammeh]

gah, no, was my fault. I shut the relay down when i was having internet problems a little earlier. It's up again now though.
ah right - okay.

Thanks. I shall get to work on this tomorrow morning i think :P

[Scawen]

Hi programmers.

Victor phoned me just now to ask me to post that he won't be able to update the InSim relay until at least Monday evening.
It's because he has an internet fault and the engineer is visiting on Monday.

Sorry about that! :(

[Krammeh]

gah that sucks. hope he can get online soon!

[Victor]

The test relay and myself are back online again now.

[Krammeh]

The test relay and myself are back online again now.

welcome back boss

[marcione]

same as for Krammeh - you can test right now. If you need access to the insim relay hosts setup page at lfsworld, let me know.


need access ;-)


thx

[91mason91]

BTW, I thought i saw that TINY NONE was a valid response now... I was connected to the LX server via the relay and was getting TINY NONE as keep-alive from the server, to which my API automatically response with TINY NONE. This results in an IR_ERR for me.

Also, would it be possible to let me set up a server and have you add it to the relay.. i want to make sure my lib does things properly and the easiest would be if i could syntesize action on the server to watch.

thanks i dont get it

[birder]

The test relay and myself are back online again now.

http://www.lfsforum.net/showthread.php?t=30492 (Race spectator) have just been launched but there are not cars on any of the servers

Can you please add the [CD] ConeDodgers servers to relay so we can try this

Thanks

[Bladerunner]

Victor...can you add my servers to the relay as well please?
Actually, [dSRC] uses two different hosts for the servers; do you need details for both or can you arrange it globally?

[Victor]

you can setup the hosts yourself now, on the insim relay setup page at lfsworld.

[banshee56]

Victor,

I would also like to be able to use the relay for CoRe's two servers.

Thanks!

[birder]

you can setup the hosts yourself now, on the insim relay setup page at lfsworld.

Hi Victor

I am going to LFSWorld, racers & hosts online, then the insim relay tab, however i am still getting

This page is currently not available due to maintenance and will not be available for a couple of days.

Please try again at a later time.

[Victor]

that message was aimed at bladerunner.

I think I'll put the test relay into live mode soon - then everybody will be able to add their host. Although I still not sure what good it'll do. But at least it's out there and available.

[sdether]

As birder pointed out there is a new spectator app out that will be able to take advantage of the V4 relay.

http://www.lfsforum.net/showthread.php?t=30492 (Race spectator) have just been launched but there are not cars on any of the servers

[Arrow.]

Hi Victor.

Any chance we can get the BOTT servers on the relay before this weekend?

Battle Of The Teams #1
Battle Of The Teams #2
Battle Of The Teams #3

[Victor]

I've opened the insim relay setup page at lfsworld to all now. So anyone can add their host to the relay again if they want to.

Also I've closed the test relay and started the relay on its real location.

So from now on, if you want to connect your relay client to the relay, connect to lfs.net:47474

I will soon start a new thread on this topic with the docs in place etc.

[Victor]

closed thread - continues here : http://www.lfsforum.net/showthread.php?t=30740