CONTENT
=======
1 License
2 Purpose
3 SSM2 Protocol Overview
4 Platforms
5 Dependencies
6 Compilation
7 Contribute
8 Implementation Notes
9 Links
1) License
==========
GPL3. See text file COPYING.txt for details.
2) Purpose
==========
LibSSM2 is a .NET library providing functionality for the SSM2
(Subaru Select Monitor 2) protocol.
Most importantly the packet classes know how to create and parse SSM2 packets.
The consumer code therefore can concentrate on the payload data itself.
Currently 8 out of 10 well known SSM2 packet types are implemented in the code.
Although there are several OSS projects using SSM2 internally,
I did not like most implementations and/or the additional work
required for filtering out the actual SSM2 protocol stuff.
So I wrote my own code from scratch the way I think it should be -
implented as a lean independent library.
To actually make use of this library you'll need an appropriate
hardware interface (typically standard OBD-II port on the car,
serial or USB port for computer) plus additional code and knowledge
in order to send and receive data (in the form of SSM2 packets) via interface.
Application code using this library has been tested with several
hardware interfaces on various operating systems.
Sooner or later, depending on spare time, I will also publish application code.
3) SSM2 Protocol Overview
=========================
SSM2 is a special car diagnostic protocol.
For details see text file SSM2_Protocol.txt.
As far as I know it is only being used by Subaru (c) cars.
Subaru is a trademark of Fuji Heavy Industries Ltd (FHI).
SSM2 operates at 4800 baud and is being used by (original)
Subaru cars from 2001+ (?).
Earlier models may use SSM1, a very different protocol, using 1953 baud.
4) Platforms
============
The code is platform independent pure C#,
compliant with the Common Language Specification (CLS).
Originally created with MonoDevelop on Linux.
Should run on any operating system provided that a .NET compatible
runtime is available.
Translating this C# code into C++ or many other languages should be fairly easy.
5) Dependencies
===============
Currently the code only needs a .NET Framework v2.0 compatible runtime
and base class assemblies.
It only references mscorlib.dll.
More recent C# language features may be used to allow modern/short syntax,
so a .NET v3+ compiler might be necessary.
6) Compilation
==============
Visual Studio (2008) solution (.sln) and C# project (.csproj) files were
generated by integrated development environment (IDE) MonoDevelop 2.4+.
Microsoft VS2010 (and possibly other .NET IDEs) should be able to open these.
This solution contains two projects in separate subfolders:
1) LibSSM2: actual LibSSM2 code
2) TestLibSSM2: NUnit tests in a separate DLL
Here are methods to compile with command line tools, especially if
you don't have an IDE installed.
mono (Linux at least)
---------------------
Tested on Linux x64.
You need to have some mono/mono-core packages installed.
a) Using xbuild (XBuild Engine, compatible to Microsoft MSBUILD)
Usually xbuild is available by Linux package "mono-devel".
Examples:
(will create Debug configuration by default)
xbuild
xbuild /property:Configuration=Debug
xbuild /property:Configuration=Release
xbuild LibSSM2.sln
xbuild LibSSM2/LibSSM2.csproj /property:Configuration=Release
b) Using gmcs (Mono C# compiler) directly
The manual page for "gmcs" says:
"The Mono C# compiler by default only references three assemblies:
mscorlib.dll, System.dll and System.Xml.dll."
Now to compile the actual library from source files:
.../LibSSM2> cd LibSSM2
.../LibSSM2/LibSSM2> gmcs -out:bin/Release/LibSSM2.dll -target:library *.cs
If all went well the resulting library file should exist, roughly 14 KiB:
bin/Release/LibSSM2.dll
Most IDEs use bin/Debug and bin/Release subdirs for output.
Advanced stuff:
Mono Ahead-of-Time compilation (AOT), creating file LibSSM2.dll.so:
mono --aot=full --optimize=all LibSSM2.dll
Decompile AOT native code:
objdump -d LibSSM2.dll.so > LibSSM2_aot.asm
Use Intel syntax instead of default (AT&T):
objdump -d LibSSM2.dll.so --disassembler-options=intel > LibSSM2_aot.masm
Windows
-------
C# compiler CSC.exe usually ships with modern Windows OS
(Vista or later) as these versions already have a .NET Framework installed.
There is a free Windows SDK downloadable from Microsoft, providing
additional tools and documentation.
Also free is the full integrated development environment (IDE)
"Visual Studio, Express Edition".
When you use additional stuff like SDK or VS, you can use
"SDK Command Prompt" or "Visual Studio Command Prompt" etc. as these
shortcuts provide paths to needed executables like csc.exe or msbuild.exe.
If you don't want to install any tool I recommend creating a .BAT file
where you can easily type the needed paths once.
a) Using MSBUILD (Microsoft (R) Build Engine)
With special command prompts, to compile the whole solution or just the
main project:
msbuild LibSSM2.sln
msbuild LibSSM2\LibSSM2.csproj
Sample content for a .BAT file using full paths:
-----
REM with .NET framework 4 (full) installed:
REM where msbuild
REM e.g.:
REM C:\WINDOWS\Microsoft.NET\Framework\v4.0.30319\MSBuild.exe
REM C:\WINDOWS\Microsoft.NET\Framework\v3.5\MSBuild.exe
SET MSBUILDPATH="C:\WINDOWS\Microsoft.NET\Framework\v4.0.30319\MSBuild.exe"
REM solution or project file
REM SET INPUT="LibSSM2\LibSSM2.csproj"
SET INPUT="LibSSM2.sln"
%MSBUILDPATH% %INPUT%
-----
b) Using CSC (Microsoft (R) Visual C# 2010 Compiler) directly
By default, optimizations are disabled. Specify /optimize+ to enable optimizations.
csc.exe is sufficient Command Prompt" or similar
csc /out:C:\LibSSM2.dll /target:library /optimize LibSSM2\*.cs
Sample content for a .BAT file using full paths:
-----
REM with .NET framework 4 (full) installed:
REM where csc
REM "C:\WINDOWS\Microsoft.NET\Framework\v4.0.30319\csc.exe"
REM "C:\WINDOWS\Microsoft.NET\Framework\v3.5\csc.exe"
REM Full path needed to allow being run from plain normal command prompt.
REM Just csc.exe is sufficient when using SDK Command Prompt or similar.
REM This would execute latest installed (e.g. v4) .NET C# compiler.
SET CSCPATH="C:\WINDOWS\Microsoft.NET\Framework\v4.0.30319\csc.exe"
SET INPUT="LibSSM2\*.cs"
SET OUTPUT="LibSSM2\bin\Release\LibSSM2.dll"
%CSCPATH% /out:%OUTPUT% /target:library /optimize %INPUT%
-----
7) Contribute
=============
Any contributions, notes, hints, bug reports etc. are welcome.
Code formatting: MonoDevelop style "Mono", Unix line endings,
standard 8 char tabs.
Some very long lines have been broken manually since
MonoDevelop feature "Edit|Format|Format Document" won't do it.
There is a simple Linux script "clean_whitespace.sh"
useful to remove trailing whitespace before committing.
8) Implementation Notes
=======================
Design goals
------------
Hopefully at least partially accomplished:
1) lean and efficient
2) reliable, especially for standard use cases
3) usable on limited Mono/.NET installations
(i.e. Compact Framework devices like PocketPC)
4) easy to use, requiring only basic SSM2 protocol knowledge
A perfect achievement of all these topics, e.g. highly efficient and
very safe to use, may not be fully possible.
These Subaru SSM2 packet classes are designed for object reusability which means
these objects are immutable.
Properties can be changed and will only affect corresponding packet bytes.
I.e. once header info has been set, one can modify payload data,
unchanged header bytes don't have to be rewritten.
This implementation also avoids many backing fields as most properties directly
rely on underlying packet buffer bytes. As an added benefit consistency problems
between properties and actual packet bytes should not occur.
Optimization
------------
Some C# compiler observations confirmed by tool "Reflector":
Applies to both Mono (2.6.4) and Windows .NET (4) C# compilers,
with optimizations turned on.
These things don't really matter here as SSM2 uses a slow data rate
but could be useful somewhere else.
a) Simple calculation subtracting a field by two constants:
int dataCount = this.count - HeaderLength - 1;
--> int num = (base.count - 5) - 1;
This is not optimal, uses two subtractions instead of one.
Even Mono full AOT compilation (on x64 at least) does not optimize
this inefficient IL away:
00000000000012b0 <Subaru_SSM2_Ssm2DataResponse_get_DataCount>:
12b0: 48 83 ec 08 sub rsp,0x8
12b4: 4c 89 3c 24 mov QWORD PTR [rsp],r15
12b8: 4c 8b ff mov r15,rdi
12bb: 49 63 47 18 movsxd rax,DWORD PTR [r15+0x18]
12bf: 83 e8 05 sub eax,0x5
12c2: 4c 8b f8 mov r15,rax
12c5: 41 ff cf dec r15d
12c8: 41 83 ff 01 cmp r15d,0x1
12cc: 7c 0e jl 12dc <Subaru_SSM2_Ssm2DataResponse_get_DataCount+0x2c>
12ce: 41 81 ff fe 00 00 00 cmp r15d,0xfe
12d5: 7f 05 jg 12dc <Subaru_SSM2_Ssm2DataResponse_get_DataCount+0x2c>
12d7: 49 8b c7 mov rax,r15
12da: eb 02 jmp 12de <Subaru_SSM2_Ssm2DataResponse_get_DataCount+0x2e>
12dc: 33 c0 xor eax,eax
12de: 4c 8b 3c 24 mov r15,QWORD PTR [rsp]
12e2: 48 83 c4 08 add rsp,0x8
12e6: c3 ret
Solution:
Grouping constants together yields expected
smaller/better IL code - 1 subtraction only:
int dataCount = this.count - (HeaderLength + 1);
--> int num = base.count - 6;
Native code of course gets slightly better as well:
00000000000012b0 <Subaru_SSM2_Ssm2DataResponse_get_DataCount>:
12b0: 48 83 ec 08 sub rsp,0x8
12b4: 4c 89 3c 24 mov QWORD PTR [rsp],r15
12b8: 4c 8b ff mov r15,rdi
12bb: 49 63 47 18 movsxd rax,DWORD PTR [r15+0x18]
12bf: 4c 8b f8 mov r15,rax
12c2: 41 83 ef 06 sub r15d,0x6
12c6: 41 83 ff 01 cmp r15d,0x1
12ca: 7c 0e jl 12da <Subaru_SSM2_Ssm2DataResponse_get_DataCount+0x2a>
12cc: 41 81 ff fe 00 00 00 cmp r15d,0xfe
12d3: 7f 05 jg 12da <Subaru_SSM2_Ssm2DataResponse_get_DataCount+0x2a>
12d5: 49 8b c7 mov rax,r15
12d8: eb 02 jmp 12dc <Subaru_SSM2_Ssm2DataResponse_get_DataCount+0x2c>
12da: 33 c0 xor eax,eax
12dc: 4c 8b 3c 24 mov r15,QWORD PTR [rsp]
12e0: 48 83 c4 08 add rsp,0x8
12e4: c3 ret
b) Windows .NET CSC uses short versions of some IL instructions:
Requiring 2 IL bytes: blt.s L_0015
while Mono compiler gmcs does not:
Requiring 5 IL bytes: blt L_001b
The behavior is exactly the same, the DLL will be slightly larger though.
Multi-threading
---------------
No special support is built in (no locks etc.) as this code has
no knowledge where it will be used.
Thread safety must be taken into account in the application
at a higher level if needed.
9) Links
========
About Subaru
------------
http://en.wikipedia.org/wiki/Subaru
http://www.subaru-global.com/
ecuExplorer
-----------
"ecuExplorer is an open-source application that will connect to a Subaru ECU"
C++, GPL2 license
http://code.google.com/p/ecuexplorer/
.NET SSM
--------
C# .NET, SSM2, GPL(?) license; library, tools and CarPC software
http://ssm.codeplex.com/
FreeSSM
-------
C++ Qt4, GPL3 license, SSM2 (SSM1 will be added soon?)
http://freessm.berlios.de/